Terraform State Management: Remote State and Backends
Configure Terraform remote state with Azure Storage, S3, and other backends for safe team collaboration — and avoid the classic state corruption mistakes that turn a plan into an incident.
Table of Contents
- Why Remote State
- Azure Storage Backend
- S3 Backend (AWS)
- Other Backends Worth Knowing
- State Locking
- State Commands Cheat Sheet
- Recovering from Problems
- Best Practices
Why Remote State
Local terraform.tfstate has serious problems for teams:
- No locking — two people running
applysimultaneously corrupts state - Secrets in plaintext — state contains sensitive values (passwords, keys, connection strings)
- Can't be shared — teammates can't access each other's laptops
- No versioning — can't recover a corrupted or accidentally-deleted state
Remote backends solve all of these: state lives in shared, encrypted, versioned storage with a locking mechanism that makes concurrent applies impossible. It's the difference between "Terraform for one person" and "Terraform for a team."
Azure Storage Backend
Create the Storage Resources
# Resource group for state
az group create --name terraform-state-rg --location uksouth
# Storage account (name must be globally unique)
az storage account create \
--name tfstate$RANDOM \
--resource-group terraform-state-rg \
--location uksouth \
--sku Standard_LRS \
--allow-blob-public-access false \
--min-tls-version TLS1_2
# Container for state files
az storage container create \
--name tfstate \
--account-name <storage-account-name>
--allow-blob-public-access false is non-negotiable — a public state container leaks every secret your infrastructure has ever known. Keep the state account separate from your app storage accounts; it's infrastructure plumbing, not application data.
Configure the Backend
# backend.tf
terraform {
backend "azurerm" {
resource_group_name = "terraform-state-rg"
storage_account_name = "tfstate12345"
container_name = "tfstate"
key = "prod.terraform.tfstate"
}
}
Authenticate
# Option 1: Azure CLI login (simplest, for humans)
az login
# Option 2: Service Principal (CI/CD)
export ARM_CLIENT_ID="..."
export ARM_CLIENT_SECRET="..."
export ARM_TENANT_ID="..."
export ARM_SUBSCRIPTION_ID="..."
# Option 3: Access key (not recommended for prod)
export ARM_ACCESS_KEY="..."
Prefer identity-based auth (CLI for people, workload identity/SP for pipelines) over access keys — keys don't expire and don't scope permissions; RBAC roles do. The identity running Terraform needs Storage Blob Data Contributor on the state container.
Initialize
terraform init
# Migrating existing local state:
terraform init -migrate-state
-migrate-state moves your local terraform.tfstate into the backend once — the one-time bridge from "local" to "remote" that turns a solo experiment into a team resource.
S3 Backend (AWS)
terraform {
backend "s3" {
bucket = "my-terraform-state"
key = "prod/terraform.tfstate"
region = "eu-west-2"
encrypt = true
dynamodb_table = "terraform-locks" # locking
}
}
The DynamoDB table provides state locking — create it once:
aws dynamodb create-table \
--table-name terraform-locks \
--attribute-definitions AttributeName=LockID,AttributeType=S \
--key-schema AttributeName=LockID,KeyType=HASH \
--billing-mode PAY_PER_REQUEST
On Terraform ≥1.10, S3 also supports use_lockfile = true — native S3 locking without the DynamoDB table. Either way, locking is the feature you're actually setting this up for; the bucket alone only solves the "can't share a laptop file" half.
Other Backends Worth Knowing
- GCS —
backend "gcs"on a Google bucket; locking built in via object generation preconditions. - HCP Terraform — HashiCorp's hosted backend: state, locking, run history, and policy checks managed for you. The zero-ops option if you can use a SaaS.
- Consul — the classic self-hosted option; works but you're now operating a Consul cluster.
- Kubernetes —
backend "kubernetes"stores state as a Secret in a cluster. Niche, but useful in K8s-native shops.
Pick the backend that matches your cloud — Azure teams use azurerm, AWS teams use s3, everyone else uses HCP Terraform or the simplest thing that gives them locking.
State Locking
Locking prevents concurrent apply runs — the mechanism that makes "two engineers deploying at once" a polite queue instead of a state-corruption incident. If you see:
Error: Error acquiring the state lock
Lock Info:
ID: abc-123
Operation: apply
Who: user@machine
Check First — Is Someone Actually Applying?
# DON'T force-unlock while a real apply is running!
# Ask your team / check CI pipelines first
The Who field names the holder — if it's a live CI job or a teammate mid-apply, wait. A stale lock (dead process, Ctrl+C'd laptop) is the only kind worth breaking.
Force Unlock (only if safe)
terraform force-unlock <lock-id>
Force-unlocking a live apply corrupts state mid-write — confirm the holder is dead before you run it. See Terraform State Lock Errors for the full diagnosis.
State Commands Cheat Sheet
# List all resources in state
terraform state list
# Show a specific resource
terraform state show azurerm_resource_group.main
# Remove a resource from state (doesn't delete in Azure)
terraform state rm azurerm_resource_group.main
# Move/rename a resource in state
terraform state mv azurerm_resource_group.old azurerm_resource_group.new
# Pull current state (view it)
terraform state pull > backup.tfstate
# Import an existing resource into state
terraform import azurerm_resource_group.main /subscriptions/xxx/resourceGroups/rg-name
state mv is the refactoring superpower — rename resources or move them into modules without destroying anything. state rm + import is the pair for adoption and handoff. Both operate on state only; your real infrastructure doesn't change.
Drift Detection
# Detect out-of-band changes made in the portal
terraform plan -refresh-only
-refresh-only shows drift between state and reality without your pending config changes mixed in — the right first command when "did anyone touch prod in the portal?" is the actual question.
Recovering from Problems
Corrupted State
# Azure blob storage keeps versions — restore one
az storage blob list \
--account-name tfstate12345 \
--container-name tfstate \
--prefix prod.terraform.tfstate
# Download an earlier version
az storage blob download \
--account-name tfstate12345 \
--container-name tfstate \
--name prod.terraform.tfstate \
--version-id <version-id> \
--file recovered.tfstate
Prevention: enable blob versioning + soft delete on the state container:
az storage account blob-service-properties update \
--account-name tfstate12345 \
--enable-versioning true
Versioned state is the difference between "corrupted state is a recovery operation" and "corrupted state is a week of import."
Resource Deleted Manually in Portal
# Terraform will try to recreate it — or remove from state:
terraform state rm <resource-address>
terraform plan # should show no changes if resource is gone
If the deletion was deliberate (someone decommissioned it in the portal), state rm aligns state with reality. If it was accidental, apply recreates it — that's the point of declarative infrastructure.
Two Applies Ran Concurrently
- Pull current remote state:
terraform state pull > current.tfstate - Compare with
terraform plan - Manually reconcile:
terraform importmissing resources orterraform state rmphantom entries
This is the mess locking exists to prevent — if it happens, the recovery is manual reconciliation, one resource at a time.
Best Practices
- Separate state per environment —
dev.tfstate,staging.tfstate,prod.tfstate(or separate storage accounts entirely) - Enable versioning — recover from corruption
- Restrict access — only CI/CD and admins should write state
- Never edit state by hand — use
terraform statecommands - Small states — split large projects into multiple stacks (networking / compute / apps); a lock on "networking" shouldn't block an app deploy
- Backend config is code — keep
backend.tfin version control, never credentials - Enable soft delete on state storage for accidental deletion protection
Example: Complete Backend Setup (Azure)
# backend.tf
terraform {
required_version = ">= 1.6"
backend "azurerm" {
resource_group_name = "terraform-state-rg"
storage_account_name = "tfstate12345"
container_name = "tfstate"
key = "prod.terraform.tfstate"
}
required_providers {
azurerm = {
source = "hashicorp/azurerm"
version = "~> 3.0"
}
}
}
Related Articles
Our tutorials and troubleshooting runbooks are written by a DevOps practitioner with hands-on experience operating Kubernetes, Terraform, CI/CD pipelines, and Linux infrastructure in production. Commands, manifests, and configurations are verified against current tooling releases. Learn more about our editorial process or report a correction or outdated flag.