☁️ Azure Fluid Relay Server Terraform Module

A Fluid Framework application needs three things from Azure:

  frs_tenant_id      ← an identifier   ✅ emitted by this module
  a service endpoint ← an identifier   ✅ emitted by this module
  an access key      ← a CREDENTIAL    🔒 deliberately NOT emitted (example 2)

ℹ️ Fluid Framework is Microsoft's library for real-time collaborative editing — several people in one document, with the service reconciling their edits. The Relay Server is the backend that does the reconciling.

⚠️ It is latency-sensitive in an unusual way. Every keystroke round-trips, so the region matters more than for most backends: put it near the users, not near the rest of the estate.

💡 It is an application dependency rather than platform infrastructure, which is why the tagging advice is to name the application that needs it. A Relay Server with no application is pure cost.

ℹ️ Most of this module's interest is in the credential handling (examples 2 and 3) rather than in the resource's own configuration, which is small: a name, a region, a storage tier and optional encryption.

# ❌ This module does NOT do this:
# output "primary_key" { value = azurerm_fluid_relay_server.this.primary_key, sensitive = true }

# ✅ It does this:
output "has_access_keys" { value = true }

🔒 Re-emitting a secret copies it into every consuming configuration's state, not just this one's. A module output is read by the caller, whose own state then contains the key — so one credential becomes two copies, for no benefit.

✅ So the module emits presence only, and tells consumers to read the key from the resource itself or from the secret store it is replicated into. That is the same place this module would have read it from.

✅ Everything a client legitimately needs is emitted: frs_tenant_id and service_endpoints. Both are identifiers rather than credentials — knowing them grants nothing — so the distinction the module draws is between "needed to connect" and "sufficient to authenticate".

⚠️ customer_managed_key_vault_key_id is emitted for the same reason. A key URI is an identifier; the key material never leaves the vault.

🔴 But note that not emitting the keys does not keep them out of state — see example 3, which is the harder problem.

primary_key   ← computed attribute
secondary_key ← computed attribute

  so Terraform reads BOTH into state on every refresh,
  whether or not any configuration references them.

🔴 This is the fact that makes the resource security-relevant, and it is not a choice this module can undo. Because the keys are computed rather than configured, they arrive in state as part of an ordinary refresh. Not outputting them (example 2) prevents a second copy; it does not prevent the first.

🔴 Consequently, a principal who can run plan against this configuration can read the keys out of the state file. Reader on this resource is a credential grant in effect, which is not what "read-only" usually implies.

✅ What follows in practice:

• The state backend must be encrypted and access-controlled — never a local file in a repository.
• Who may run a plan against this configuration is a security decision, not just an operational one.
• Consider isolating this resource in its own state, so a broad plan permission elsewhere does not include it.

✅ plan_access_is_credential_access is emitted as a constant true so the fact appears in a review rather than being discovered after somebody is granted plan rights. This library's rule is that where reading a resource means reading its keys, that belongs in the permissions table — so it is also in the RBAC section above.

⚠️ A sensitive = true marking would not help. Sensitivity redacts plan output; it does not encrypt state. Saying "the keys are sensitive" without saying "and they are plaintext in state" would be worse than saying nothing, because it invites relaxing the control that actually matters.

storage_sku = "standard" # ✅
storage_sku = "basic"    # ✅
storage_sku = "Standard" # ❌ rejected — and this is the spelling every other Azure SKU uses

🔴 Almost every SKU in Azure is capitalised, and this one is not. Standard is what muscle memory types and the API rejects it, so the module rejects it offline with a message naming the trap:

Error: Invalid value for variable

  storage_sku must be "standard" or "basic" — note the LOWERCASE, which is unusual for
  an Azure SKU. "Standard" and "Basic" are rejected by the API. Omit the variable
  entirely to let Azure choose.

✅ Omitting it is this module's default, because the field is computed as well as optional — so Azure chooses, and the module does not invent a tier the provider does not default. The output reports whatever was chosen.

🔴 It is force-new. Changing the storage tier replaces the server, which issues new keys and new endpoints — so every client has to pick them up. That makes the tier a create-time decision rather than something to tune.

💡 basic is the cheaper tier and adequate for development. Choosing it deliberately for a non-production server is reasonable; discovering later that production is on it is not, and there is no in-place fix.

identity = {
  type         = "UserAssigned"      # 🔴 SystemAssigned alone will NOT work
  identity_ids = [module.uai.id]
}

customer_managed_key = {
  key_vault_key_id          = var.kv_key_versionless_id # 💡 versionless
  user_assigned_identity_id = module.uai.id                # must be in identity_ids above
}

✅ First, what this does and does not change. Data is encrypted at rest either way — omitting the block means platform-managed keys, not plaintext. The reason to want a customer-managed key is custody and revocation, not encryption.

🔴 The identity that unwraps the key must be user-assigned and must be assigned to this server. The module validates that user_assigned_identity_id appears in identity.identity_ids, because otherwise the failure arrives at apply as a Key Vault access error — sending the reader to the vault instead of to the identity list three lines above:

Error: Invalid value for variable

  customer_managed_key.user_assigned_identity_id names an identity that is not in
  identity.identity_ids, so it is not assigned to this server and cannot reach Key
  Vault. [...] Left as-is, this fails at apply as a key-access error pointing at Key
  Vault rather than at the identity list.

⚠️ The identity also needs wrap, unwrap and get on the key — a Key Vault grant this module cannot make. Compose terraform-azurerm-role-assignments for it. Without that grant the server is created and cannot decrypt, which is a working apply and a broken service.

🔴 The whole block is force-new. Adding, changing or removing a customer-managed key replaces the server, and therefore its keys and endpoints.

💡 Use a versionless key ID. A pinned version means key rotation requires replacing the server — which the module recommends against but does not forbid, because pinning is occasionally intended.

service_endpoints  → populated ✅  use this
orderer_endpoints  → ALWAYS EMPTY ⚠️
storage_endpoints  → ALWAYS EMPTY ⚠️

⚠️ The provider documents both as deprecated in a future Fluid Relay version and always empty today. An empty list from either is correct behaviour, not a failure — but it looks exactly like a failure if you do not know.

✅ So the module emits them anyway, with a constant flag explaining why. Omitting them would leave a reader wondering where they went; emitting them silently would leave someone debugging an empty list for an afternoon.

✅ Use service_endpoints and frs_tenant_id — those are what a Fluid client actually needs (example 1).

💡 This is a small instance of a general habit worth having: when a provider tells you a field is vestigial, say so at the point somebody will read it, rather than passing the confusion straight through.

ℹ️ orderer_and_storage_endpoints_are_always_empty is the constant that carries the explanation.

identity = { type = "SystemAssigned" }                                       # the default
identity = { type = "UserAssigned", identity_ids = [module.uai.id] }
identity = { type = "SystemAssigned, UserAssigned", identity_ids = [module.uai.id] }

✅ The empty call yields a system-assigned identity, this suite's preferred alternative to embedded credentials, and the same shape its other identity-bearing modules use — so the two read alike at a call site.

⚠️ "SystemAssigned,UserAssigned" without the space is rejected, and the provider's own error is not especially clear about why. The module validates the exact set of three legal strings.

✅ identity_ids is required with UserAssigned, and rejected without it. Both directions, because IDs that silently do nothing read like configuration that took effect.

⚠️ identity_ids takes the identity's Resource ID, not its principal or client ID. All three are GUID-ish values people copy interchangeably, so the module checks the path.

💡 identity_principal_id is the value to grant roles to — not id, not frs_tenant_id. Getting those confused produces a role assignment against nothing recognisable.

# ✅ In place:
tags = { app = "collab-docs", key_rotated = "2026-09-01" }

# 🔴 Force-new — and each replacement issues NEW KEYS and NEW ENDPOINTS:
name                 = "frs-collab-docs-v2"
location             = "westus2"
storage_sku          = "basic"
customer_managed_key = { ... }

🔴 Replacing this server is a client-visible event. New access keys and new endpoints mean every Fluid application has to pick up new configuration — so a casual rename is an application deployment.

✅ Which makes tags unusually load-bearing, as it is the only mutable field. It is the place to record which application depends on the server, who owns it, and when the keys were last rotated.

⚠️ Plan a replacement as a migration, not an edit: stand up the new server, move clients, retire the old one. There is no in-place path for any of the four force-new fields.

💡 Key rotation is not a Terraform operation. Azure regenerates the keys out of band; this module neither rotates nor emits them. Recording the rotation date in a tag is the cheapest way to make it visible at all.

output "fluid_relay_review" {
  value = {
    id          = module.fluid_relay.id
    tenant      = module.fluid_relay.frs_tenant_id
    endpoints   = module.fluid_relay.service_endpoints
    cmk         = module.fluid_relay.uses_customer_managed_key
    cmk_key     = module.fluid_relay.customer_managed_key_vault_key_id
    identity    = module.fluid_relay.identity_principal_id # must not be null
    keys_exist  = module.fluid_relay.has_access_keys                  # always true
    plan_is_cred = module.fluid_relay.plan_access_is_credential_access # always true
  }
}

🔴 plan_is_cred is a constant true, and it is a prompt rather than a value. It means: confirm the state backend is encrypted and access-controlled, and confirm who can run a plan against this configuration (example 3).

🔒 cmk is a genuine choice, and false is not a failure. Platform-managed encryption is still encryption; true means you have taken custody of the key and accepted the force-new constraint that comes with it (example 5).

⚠️ cmk_key is worth reading for a version segment. A pinned version means rotation requires replacing the server.

⚠️ identity must not be null. A server with no identity cannot use a customer-managed key and has nothing to grant roles to.

💡 What no output can tell you is whether the keys have ever been rotated, or who has read them out of state. Both are outside Terraform.

terraform import 'module.fluid_relay.azurerm_fluid_relay_server.this' \
  "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-collab/providers/Microsoft.FluidRelay/fluidRelayServers/frs-collab-docs"

🔴 The moment you import, the access keys are in your state. That is worth knowing before running the command rather than after (example 3) — so confirm the backend first.

🔴 Restate storage_sku exactly, in lowercase. It is force-new, so a mismatch — including a capitalisation mismatch that the module would otherwise reject — produces a plan that replaces the server and reissues its keys.

⚠️ Restate customer_managed_key if the live server has one, for the same reason. Omitting it is a replacement, not a no-op.

The offline gate

terraform init -backend=false
terraform validate
terraform fmt -check

✅ What it proves: storage_sku is lowercase and one of the two legal values, identity.type is one of the three legal strings, identity_ids is present exactly when the type requires it and every entry is a user-assigned identity path, the Key Vault key ID looks like a key URI, and the customer-managed key's identity is one of the assigned identities.

💡 Proved by evaluating the conditions in terraform console inside the module, which does fire root-module variable validations — unlike terraform validate on a calling configuration. "Standard" fires the lowercase check, and a customer_managed_key naming an unassigned identity fires the pairing check.

⚠️ What it cannot prove: that the Key Vault grant exists, that the region is near the users, or anything at all about the keys.

terraform destroy on this module:
  removes the SERVER          ->  its access keys and endpoints are gone
                              ->  every Fluid client using it stops working immediately
  the Key Vault key survives  ->  and so does the user-assigned identity
  the keys remain in old state versions  ->  🔒 which is worth remembering

🔴 This destroy is immediately client-visible. There is no soft delete and no grace period: the endpoints stop answering and collaborative sessions end.

🔒 And note the last line. The access keys were in state, so they are in whatever state history your backend keeps — versioned blobs, snapshots, backups. Destroying the server does not remove them from there, and the keys are no longer rotatable because the server is gone. If that matters, the state history is what needs attention.

✅ The Key Vault key and the identity survive, which is the right blast radius — they are shared, longer-lived resources this module only references.

💡 A CanNotDelete management lock is worth considering for a production server, given how abrupt the failure mode is. Note that a lock prevents deletion, not the force-new replacement of example 8 — and lifecycle is not valid inside a module block, so prevent_destroy is not available to a caller.

provider "azurerm" {
  features {}
}

module "rg" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-group.git?ref=v1.0.0"

  name     = "rg-collab"
  location = "eastus" # 🔴 near the USERS — every keystroke round-trips (example 1)
}

# ── A user-assigned identity, because a customer-managed key requires one ────
module "uai" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-user-assigned-identity.git?ref=v1.0.0"

  name                = "uai-fluid-relay"
  resource_group_name = module.rg.name
  location            = module.rg.location
}

# ── The identity needs wrap/unwrap/get on the key. This module cannot grant it ──
# ℹ️ module.kv and module.kv_key are the caller's key vault and key, elided here.
module "cmk_grant" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-role-assignments.git?ref=v1.0.0"

  scope = var.kv_id

  role_assignments = {
    fluid_relay_cmk = {
      role_definition_name = "Key Vault Crypto Service Encryption User"
      principal_id         = module.uai.principal_id
    }
  }
}

# ── This module: the server ─────────────────────────────────────────────────
module "fluid_relay" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-fluid-relay-server.git?ref=v1.0.0"

  name                = "frs-collab-docs"
  resource_group_name = module.rg.name
  location            = module.rg.location

  # 🔴 LOWERCASE, and force-new (example 4).
  storage_sku = "standard"

  # 🔴 A customer-managed key needs a USER-assigned identity (example 5).
  identity = {
    type         = "UserAssigned"
    identity_ids = [module.uai.id]
  }

  customer_managed_key = {
    key_vault_key_id          = var.kv_key_versionless_id # 💡 versionless
    user_assigned_identity_id = module.uai.id                # in identity_ids above
  }

  # The only mutable field, so it carries what changes (example 8).
  tags = {
    app         = "collab-docs"
    owner       = "productivity"
    key_rotated = "2026-09-01"
  }

  depends_on = [module.cmk_grant] # the grant must exist before the server needs the key
}

output "fluid_posture" {
  value = {
    # ✅ What a Fluid client needs — identifiers, not credentials (examples 1 and 2).
    tenant    = module.fluid_relay.frs_tenant_id
    endpoints = module.fluid_relay.service_endpoints
    # 🔒 Posture.
    cmk          = module.fluid_relay.uses_customer_managed_key          # true here
    plan_is_cred = module.fluid_relay.plan_access_is_credential_access   # always true
    # 🔒 The keys are NOT here, deliberately (example 2).
  }
}

🔒 What the composition gets right: a user-assigned identity because the customer-managed key requires one, the Key Vault grant made explicitly with depends_on because the server needs it before it can decrypt, a versionless key so rotation does not replace the server, the region chosen for the users rather than the estate, the lowercase SKU stated explicitly, and an output that publishes the identifiers a client needs while publishing no credential.

⚠️ What no plan will tell you: whether the state backend is encrypted — which matters more here than in most modules, because the keys are in it (example 3).

💡 depends_on is used here deliberately, and it is the one place in this composition where an attribute reference would not express the dependency: the server does not consume anything from the role assignment, but it needs the grant to exist. That is exactly the case depends_on is for.