Terraform

Terraform State Management: Remote State and Backends

Intermediate
15 minutes
Updated October 2026

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

Local terraform.tfstate has serious problems for teams:

  • No locking — two people running apply simultaneously 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

  1. Pull current remote state: terraform state pull > current.tfstate
  2. Compare with terraform plan
  3. Manually reconcile: terraform import missing resources or terraform state rm phantom entries

This is the mess locking exists to prevent — if it happens, the recovery is manual reconciliation, one resource at a time.

Best Practices

  1. Separate state per environment — dev.tfstate, staging.tfstate, prod.tfstate (or separate storage accounts entirely)
  2. Enable versioning — recover from corruption
  3. Restrict access — only CI/CD and admins should write state
  4. Never edit state by hand — use terraform state commands
  5. Small states — split large projects into multiple stacks (networking / compute / apps); a lock on "networking" shouldn't block an app deploy
  6. Backend config is code — keep backend.tf in version control, never credentials
  7. 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"
    }
  }
}
Written & Reviewed by Yasir Masood, CloudOpsGuide Editor

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.

More Terraform Guides

View all in Terraform →
Beginner · 14 minutes
Terraform 101: Managing AWS Infrastructure as Code
Clicking through the AWS console works until it doesn't — nobody remembers what they clicked, environments drift apart, and "it works in staging" becomes a meme. Terraform fixes this by making infrastructure code: you describe what you want in HCL (HashiCorp Configuration Language), and Terraform makes the cloud match it. This guide follows the official HashiCorp AWS get-started path — install → write configuration → init → apply → change → destroy — so by the end you'll have provisioned and torn down a real EC2 instance.
Read guide
Intermediate · 10 minutes
Terraform AWS Modules: Production AWS in 20 Lines of HCL
Writing raw Terraform for AWS works — until you need a VPC with public and private subnets across three availability zones, NAT gateways, route tables, and flow logs. That's easily 500 lines of HCL and a week of testing. The terraform-aws-modules organization on GitHub exists because everyone kept writing that same 500 lines. It's a community collection of 60+ battle-tested modules covering VPC, EKS, RDS, IAM, Lambda, ECS, S3, and more — each maintained, versioned, and documented. This tutorial shows how to use them properly, from the registry to a working production-shaped network.
Read guide
Beginner · 12 minutes
Terraform Azure Service Principal: Authentication Guide
Create and configure Azure Service Principals for Terraform authentication with step-by-step instructions.
Read guide