ADR-009: Dedicated Resource Group for Terraform State Storage#

Status#

Accepted

Context#

Terraform requires a remote state backend (an Azure Storage Account) to exist before terraform init can run — a chicken-and-egg dependency that lives outside Terraform’s own management. The question is where that storage account should live: in each environment’s resource group, in a shared platform resource group, or in its own dedicated resource group.

The project uses Terraform workspaces to manage three environments (dev, staging, prd), each with its own resource group. Terraform state is per-workspace but the storage account and blob container are shared across all workspaces — each workspace writes to a different state key within the same container.

Decision#

Place the Terraform state storage account in a conceptually separate resource group, distinct from both the per-environment resource groups and the shared platform resource group (which hosts the ACR).

In bootstrap.sh and docs/operations/bootstrap.md, this is expressed via the TF_VAR_tf_state_resource_group_name environment variable. For a minimal single-RG deployment, operators may point it at the same RG as everything else; for a multi-RG deployment, it gets its own dedicated RG.

Options Considered#

Option A: State in each environment’s RG (rejected)#

Each environment (dev, staging, prd) would have its own storage account holding its own state file.

  • Pro: Self-contained — terraform destroy on an environment cleans up everything including its state.

  • Con: Circular dependency — the storage account must exist before terraform init, but terraform destroy would delete it, leaving Terraform unable to reason about what it just destroyed. Recovery requires recreating the storage account and re-importing state.

  • Con: Multiplies bootstrap work — every new environment needs its own pre-Terraform az storage account create step, increasing the operational burden and the number of globally-unique names to manage.

  • Con: No shared state history — you lose the ability to inspect or compare state across environments from a single location.

Option B: State in a shared platform RG alongside the ACR (rejected)#

One shared resource group holds both the Terraform state storage account and the container registry.

  • Pro: Fewer resource groups to manage. One bootstrap step creates both the state backend and the ACR.

  • Con: Conflates two resources with different lifecycle and access properties. The ACR is a shared, pull-heavy, promotable artifact store that may eventually be geo-replicated or granted cross-team read access. The state storage is a write-heavy, environment-internal, never-shared data store. Mixing them means ACR lifecycle operations (retention policies, geo-replication, third-party access grants) risk accidentally affecting state storage, and vice versa.

  • Con: Different ownership boundaries — the ACR may eventually be delegated to a platform team, while state storage should remain in the hands of whoever owns Terraform. Co-locating them in one RG makes this delegation harder.

Option C: State in its own dedicated RG (chosen)#

A dedicated resource group (e.g. rg-qfa-tfstate) holds only the Terraform state storage account, a blob container, and a CannotDelete lock.

  • Pro: Clean blast radius — accidental deletion of an environment RG or the platform RG cannot destroy state.

  • Pro: Minimal surface — the RG contains exactly one resource, making RBAC and lifecycle management trivial. Only principals that run terraform init / apply need access.

  • Pro: Adding a new environment requires zero changes to the state infrastructure — terraform workspace new <env> writes a new state key in the existing container.

  • Pro: The CannotDelete lock on the storage account provides defense in depth. An accidental az storage account delete is the single most destructive operation in this architecture; isolating the SA in its own locked RG makes that accident harder to trigger.

  • Con: One more resource group to create during bootstrap (a one-time az group create command).

Consequences#

  • bootstrap.sh reads TF_VAR_tf_state_resource_group_name to know where to create the storage account. This variable is shell-only — it cannot be a Terraform variable because backend blocks forbid variable interpolation.

  • terraform init receives the same value via -backend-config="resource_group_name=...".

  • bootstrap.sh adds a CannotDelete lock to the storage account immediately after creation.

  • For a single-RG deployment, TF_VAR_tf_state_resource_group_name can equal TF_VAR_resource_group_name — the conceptual separation exists in the variable structure even when the physical RGs are the same.

  • Migrating from single-RG to multi-RG is a config change (re-export env vars, re-init with -backend-config, migrate state), not a code change.

Participants#

Marius