ContextQMD
Back to Terragrunt

Azure Backend

docs/src/data/experiments/azure-backend.mdx

1.1.45.1 KB
Original Source

import Since from '@components/Since.astro'; import Before from '@components/Before.astro';

Experimental support for the Azure Storage (azurerm) remote state backend.

azure-backend - What it does

<Before version="1.1.2"> Terragrunt already recognizes `backend = "azurerm"` in `remote_state` blocks regardless of whether this experiment is enabled, and currently falls through to the native OpenTofu/Terraform `azurerm` backend. This experiment reserves the flag for the long-term goal of having Terragrunt manage Azure Storage accounts, blob containers, and state blobs in the same way it already manages S3 buckets and GCS buckets: automatic bootstrap, delete, migrate, and direct state reads for [`dependency-fetch-output-from-state`](/reference/experiments/active#dependency-fetch-output-from-state).

In its current form (initial registration) the experiment only:

  • Reserves the azure-backend experiment name.
  • Reserves the azurerm backend slot in Terragrunt's remote state layer.

The flag itself currently has no behavioral effect: there is no Azure SDK code, authentication logic, or storage account management yet, and the backend is not gated on the flag. Functional behavior will land in subsequent releases. </Before>

<Since version="1.1.2"> Enabling this experiment turns on Terragrunt-managed lifecycle operations for the Azure Storage (`azurerm`) remote state backend, matching what Terragrunt already does for S3 buckets and GCS buckets:
  1. Bootstrap: creates the resource group (when allowed), storage account, and blob container backing the state, and converges blob versioning and optional soft delete on both new and pre-existing accounts.
  2. Delete: removes state blobs or entire containers, with confirmation prompts.
  3. Migrate: moves state blobs within the same storage account (cross-account migration is refused with guidance to migrate manually).

Authentication supports six methods, resolved in the following order:

  1. SAS token
  2. Storage account access key
  3. Service principal
  4. Managed identity (MSI)
  5. OIDC / workload identity
  6. Azure AD (use_azuread_auth or the default credential chain, which honors az login)

ARM_* and AZURE_* environment variable fallbacks are applied, and public, US Government, and China clouds are supported via the environment key.

Without the experiment enabled, these lifecycle operations return an error naming the experiment; normal state reading and writing is handled by the native OpenTofu/Terraform azurerm backend.

When both this experiment and dependency-fetch-output-from-state are enabled, Terragrunt can read dependency outputs directly from the Azure state blob without initializing the dependency or running tofu output/terraform output. State protected with customer_provided_key, and configurations that rely on native-only authentication, metadata_host, or timeout_seconds, continue through the native backend path. This preserves the backend's identity, endpoint, and decryption behavior.

See the Azure Storage backend documentation for configuration keys and known limitations. </Since>

azure-backend - How to enable it

bash
# Via CLI flag
terragrunt --experiment azure-backend run -- plan

# Via environment variable
export TG_EXPERIMENT=azure-backend
terragrunt run -- plan

azure-backend - How to provide feedback

Track and discuss this experiment in gruntwork-io/terragrunt#4307. When reporting issues or providing feedback, please include:

  • The Azure authentication method you are using (Azure AD, MSI, service principal, SAS, access key).
  • The cloud environment (public, government, china).
  • Any errors encountered during init, plan, or backend bootstrap.

azure-backend - Criteria for stabilization

To transition the azure-backend feature to a stable release, the following must be addressed, at a minimum:

  • internal/azurehelper package wrapping the Azure SDK with a builder pattern matching awshelper/gcphelper.
  • Bootstrap of storage accounts and blob containers, including versioning and soft delete convergence.
  • Optional RBAC role assignment for use_azuread_auth during bootstrap (the data-plane role must currently be granted manually).
  • Delete operations for state blobs and containers, with confirmation prompts, and state migration within a storage account.
  • Direct state file reads from Azure blobs for --dependency-fetch-output-from-state.
  • Documentation covering authentication methods, configuration keys, and troubleshooting.
  • End-to-end live coverage against a real subscription for container bootstrap, blob versioning convergence, backend delete, and direct dependency state reads, behind the azure build tag.
  • End-to-end live coverage for resource group and storage account creation, soft-delete retention convergence, and state migration. The current live tests assume a pre-existing storage account.
  • Community feedback on real-world usage.