Azure Storage Backend

In this guide you will configure Azure Storage as a remote Terraform backend and deploy infrastructure using that backend. It explains required backend settings, authentication options, initializing and migrating state, how state locking works (blob leases), and security best practices.

Overview

The backend block (inside the terraform block) tells Terraform where to store the state file. It must reference an existing Azure Storage account, container, and blob (key). Terraform will not create these backend resources during terraform init.
You can still manage a storage account as a Terraform resource in your configuration (so it appears in state), but that resource cannot serve as the backend for the same run that creates it — the backend must exist before terraform init.
Authentication to the Azure azurerm backend can use an account key (ARM_ACCESS_KEY) or Azure AD credentials (service principal or managed identity). Azure AD-based authentication is recommended for CI/CD.

The backend storage account and container must already exist before running terraform init. Terraform cannot use a resource that it will create during the same run as its backend.

Do not attempt to create the storage account/container/blob in the same Terraform run that you declare as your backend. Terraform needs the backend to exist before it can initialize remote state.

Backend configuration example

A minimal azurerm backend block:

terraform {
  backend "azurerm" {
    resource_group_name  = "rg-remote-state-demo"
    storage_account_name = "stateremotestorage"
    container_name       = "statecontainer"
    key                  = "remotestate.tfstate"
  }
}

resource_group_name: Resource group containing the storage account.
storage_account_name: Name of the storage account where state will be stored.
container_name: Blob container within the storage account.
key: Blob name (file) used for the state, e.g. remotestate.tfstate. Note: this is not an access key.

Backend parameters at a glance

Parameter	Purpose	Example
`resource_group_name`	Resource group that holds the storage account	`rg-remote-state-demo`
`storage_account_name`	Storage account to hold state	`stateremotestorage`
`container_name`	Blob container for state blobs	`statecontainer`
`key`	Blob filename used to store state	`remotestate.tfstate`

Example Terraform storage account resource (not usable as backend in same run)

You can create the storage account via Terraform, but remember: if you plan to use it as the backend, it must already exist before terraform init.

resource "azurerm_storage_account" "example" {
  name                          = var.storage_account_name
  location                      = "West Europe"
  resource_group_name           = "rg-remote-state-demo"
  account_tier                  = "Standard"
  account_replication_type      = "LRS"
  public_network_access_enabled = false
}

Authenticate Terraform to the Azure backend

Authentication options:

Method	Description	Notes
Storage account key	Set `ARM_ACCESS_KEY` environment variable with the storage account key	Quick, but less secure for CI/CD
Azure AD Service Principal	Use `ARM_CLIENT_ID`, `ARM_CLIENT_SECRET`, `ARM_TENANT_ID`, `ARM_SUBSCRIPTION_ID`	Recommended for CI/CD with least privilege
Managed Identity	Use a managed identity for a VM or CI runner	Best practice for Azure-hosted agents

If using the storage account key, fetch and export it with the Azure CLI:

RESOURCE_GROUP_NAME="rg-remote-state-demo"
STORAGE_ACCOUNT_NAME="stateremotestorage"
CONTAINER_NAME="statecontainer"

ACCOUNT_KEY=$(az storage account keys list \
  --resource-group "$RESOURCE_GROUP_NAME" \
  --account-name "$STORAGE_ACCOUNT_NAME" \
  --query '[0].value' -o tsv)

export ARM_ACCESS_KEY="$ACCOUNT_KEY"
echo "$ARM_ACCESS_KEY"

For CI/CD pipelines, prefer Azure AD service principals or managed identities and avoid embedding account keys.

Initialize, plan, and apply

After adding the backend block to your configuration and exporting any required credentials:

Initialize Terraform to configure the backend and providers:

terraform init

Sample sanitized init output:

Initializing the backend...
Successfully configured the backend "azurerm"! Terraform will automatically use this backend unless the backend configuration changes.

Initializing provider plugins...
- Reusing previous version of hashicorp/azurerm from the dependency lock file

Terraform has been successfully initialized!

Inspect changes and apply:

terraform plan
terraform apply -var "storage_account_name=stremotestatedemo11" -auto-approve

Sample sanitized apply output:

Acquiring state lock. This may take a few moments...
azurerm_resource_group.rg: Creation complete after 32s [id=/subscriptions/.../resourceGroups/rg-remote-state-demo]
azurerm_virtual_network.vnet: Creation complete after 12s [id=/subscriptions/.../providers/Microsoft.Network/virtualNetworks/vnet-demo]
azurerm_storage_account.example: Creation complete after 1m23s [id=/subscriptions/.../providers/Microsoft.Storage/storageAccounts/stremotestatedemo11]
Releasing state lock. This may take a few moments...

Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

When Terraform runs, it acquires a lock on the state blob. In Azure Storage this is implemented as a blob lease. If the run is interrupted, the lease may remain active and block subsequent Terraform operations until released or broken.

The image shows a Microsoft Azure portal interface displaying a container named "statecontainer" with a blob file "remotestate.tfstate" that is "Leased" and has an access tier set to "Hot (Inferred)."

If a lease persists after an interrupted run, you can manually break the lease in the Azure portal for that blob to resume operations.

Migrating local state to a remote backend

If your configuration currently uses local state and you add a backend block, terraform init will detect the existing local state and prompt to migrate it to the new backend:

$ terraform init
Initializing the backend...
Acquiring state lock. This may take a few moments...

Do you want to copy existing state to the new backend?
Pre-existing state was found while migrating the previous "local" backend to the newly configured "azurerm" backend. No existing state was found in the newly configured "azurerm" backend. Do you want to copy this state to the new "azurerm" backend? Enter "yes" to copy and "no" to start with an empty state.

Enter a value: yes

Releasing state lock. This may take a few moments...

Successfully configured the backend "azurerm"! Terraform will automatically use this backend unless the backend configuration changes.

If you confirm, Terraform uploads your local state to the remote backend and removes the local state file.

Full provider and resources example (VS Code walkthrough)

A simple configuration that includes provider, resource group, storage account, and virtual network. Create the storage account/container in the portal or otherwise before using it as a backend.

provider "azurerm" {
  features {}
  # Optionally specify subscription_id if needed
  # subscription_id = "00000000-0000-0000-0000-000000000000"
}

resource "azurerm_resource_group" "rg" {
  name     = "rg-remote-state-demo"
  location = "West Europe"
}

resource "azurerm_storage_account" "sa" {
  name                     = "stremotestatedemo11"
  resource_group_name      = azurerm_resource_group.rg.name
  location                 = azurerm_resource_group.rg.location
  account_tier             = "Standard"
  account_replication_type = "LRS"
  public_network_access_enabled = false
}

resource "azurerm_virtual_network" "vnet" {
  name                = "vnet-demo"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  address_space       = ["192.168.0.0/16"]
}

After creating the storage account and a container (manually or ahead of time), add the backend block and run:

terraform init
terraform plan
terraform apply -auto-approve

During operations Terraform will:

Acquire a blob lease (state lock) on the remote blob.
Refresh resource state from Azure.
Release the lease when finished (or leave it if the run is interrupted).

How the lease looks in the portal

When Terraform holds the blob lease, the Azure portal will show the blob with properties including the URL, creation time, size, encryption status, and an active lease. If the lease remains after an interrupted run, break the lease in the portal.

The image shows a Microsoft Azure portal interface displaying the details of a blob storage item named "remotestate.tfstate" within a container, including its properties like URL, creation time, size, and encryption status.

Security recommendations

Restrict storage account and container access to only necessary identities and roles (least privilege).
Prefer Azure AD-based authentication (service principal or managed identity) over storage account keys in automation and CI/CD.
Keep storage accounts private: disable public network access and use service endpoints or private endpoints where applicable.
Enable encryption at rest (enabled by default) and consider customer-managed keys for additional control.
Monitor access and audit logs for unexpected actions against the state container.

Troubleshooting tips

If terraform init fails to configure the backend, verify the storage account, container, and key exist and that the credentials used have appropriate permissions.
If Terraform operations are blocked due to a blob lease, check the Azure Storage container and break the lease from the portal if appropriate.
Use az storage blob lease break (Azure CLI) if you prefer CLI-based lease management (ensure you have adequate permissions).

Summary

Use the azurerm backend in Terraform to store state in Azure Storage and enable collaboration and locking.
Ensure the backend storage account, container, and blob key are present before terraform init.
Authenticate using ARM_ACCESS_KEY (account key) or, preferably, Azure AD credentials (service principal or managed identity).
terraform init can migrate local state to the remote backend.
Terraform uses blob leases for state locking; if a lease persists after an interrupted run, you can break it in the portal.

Introduction

Infrastructure as Code Fundamentals

Terraform Cloud

Setting up environment

Azure Context for Terraform

HashiCorp Configuration Language

Terraform Providers

Variables

Outputs and Dependencies

Iteration and Logic

Advanced Constructs

Terraform State Fundamentals

Remote State

Terraform Workspaces

Terraform CLI

Lifecycle Meta-Arguments

Data Sources

Provisioners

Debugging Terraform

Terraform Modules

Azure DevOps Integration

Azure Pipelines for Terraform

Azure Storage Backend

Overview

Backend configuration example

Backend parameters at a glance

Example Terraform storage account resource (not usable as backend in same run)

Authenticate Terraform to the Azure backend

Initialize, plan, and apply

Migrating local state to a remote backend

Full provider and resources example (VS Code walkthrough)

How the lease looks in the portal

Security recommendations

Troubleshooting tips

Summary

Links and References

Watch Video

​Overview

​Backend configuration example

​Backend parameters at a glance

​Example Terraform storage account resource (not usable as backend in same run)

​Authenticate Terraform to the Azure backend

​Initialize, plan, and apply

​Migrating local state to a remote backend

​Full provider and resources example (VS Code walkthrough)

​How the lease looks in the portal

​Security recommendations

​Troubleshooting tips

​Summary

​Links and References

Watch Video

Overview

Backend configuration example

Backend parameters at a glance

Example Terraform storage account resource (not usable as backend in same run)

Authenticate Terraform to the Azure backend

Initialize, plan, and apply

Migrating local state to a remote backend

Full provider and resources example (VS Code walkthrough)

How the lease looks in the portal

Security recommendations

Troubleshooting tips

Summary

Links and References