State in depth
What state contains and why it matters
terraform.tfstate is JSON containing, for every managed resource: its address, provider, real IDs, and all attributes (including computed ones like ARNs, IPs — and secrets like generated passwords or private keys). Terraform needs it to:
- know which real resource corresponds to which block (
aws_instance.web→i-0abc...), - compute diffs and dependencies for deletion order,
- cache attributes for performance.
Consequences:
- State is sensitive — treat it like a secret: encrypted storage, tight access, never in Git.
- Losing state means Terraform forgets resources (they keep running unmanaged; recreating them would conflict) — you'd have to re-import.
- Concurrent writes corrupt state — you need locking.
Remote backends
Local state (terraform.tfstate in the working dir) doesn't work for teams. Use a remote backend: shared, durable, versioned, locked. On AWS, the S3 backend:
terraform {
backend "s3" {
bucket = "acme-terraform-state-123456789012"
key = "prod/network/terraform.tfstate" # one key per stack/environment
region = "ap-south-1"
encrypt = true
kms_key_id = "alias/terraform-state"
use_lockfile = true # S3-native locking (Terraform 1.11+)
}
}
- Locking: newer Terraform versions lock using a lock file in S3 itself (
use_lockfile, S3 conditional writes). Older setups use a DynamoDB table (dynamodb_table = "terraform-locks") — now deprecated but you'll see it everywhere, so know both. - Bucket settings: versioning on (recover old state), SSE-KMS encryption, Block Public Access, a bucket policy restricting access to the Terraform roles, optionally object lock/MFA delete, access logging.
- Bootstrap problem: the state bucket can't be created by the configuration that uses it. Create it once with a small separate bootstrap configuration (with local state, or later migrated), CloudFormation, or by hand — then everything else uses it.
- Backend config can't use variables; pass per-environment values with
-backend-config=prod.s3.tfbackendatinit.
Other backends: HCP Terraform / Terraform Enterprise (remote runs, state, policy), GCS, azurerm, Kubernetes, PostgreSQL. OpenTofu adds client-side state encryption.
Locking in practice
When someone runs plan/apply, Terraform acquires the lock; a second run waits or fails with Error acquiring the state lock showing who holds it. If a run crashed and left the lock behind:
terraform force-unlock <LOCK_ID> # only after confirming no run is actually in progress
State commands
terraform state list # all managed addresses
terraform state show aws_instance.web # attributes of one resource
terraform state mv aws_instance.web aws_instance.app # rename an address (prefer `moved` blocks)
terraform state rm aws_s3_bucket.legacy # stop managing (does NOT delete the bucket)
terraform state pull > backup.tfstate # download
terraform state push backup.tfstate # upload (dangerous; last resort)
Refactoring without destroying: moved and removed
moved {
from = aws_instance.web
to = aws_instance.app
}
moved {
from = aws_s3_bucket.logs
to = module.logging.aws_s3_bucket.this # moving into a module
}
removed { # Terraform 1.7+: forget without destroying
from = aws_s3_bucket.legacy
lifecycle { destroy = false }
}
Without moved, renaming a block makes Terraform destroy the old and create a new resource — catastrophic for databases. moved blocks are reviewable in PRs, unlike ad-hoc state mv.
Importing existing infrastructure
Bringing a manually created resource under Terraform:
import { # Terraform 1.5+: declarative import
to = aws_s3_bucket.reports
id = "acme-reports-prod"
}
resource "aws_s3_bucket" "reports" {
bucket = "acme-reports-prod"
}
terraform plan -generate-config-out=generated.tf # Terraform can draft the resource block for you
terraform apply
# legacy CLI form: terraform import aws_s3_bucket.reports acme-reports-prod
After import, adjust the configuration until plan shows no changes.
Drift
Drift = real infrastructure changed outside Terraform (console edits, scripts, other tools). plan reveals it. Options:
- Revert reality to code:
apply. - Accept reality into code: update the configuration to match, then plan shows no changes.
- Accept into state only:
terraform apply -refresh-onlyupdates state to match reality without changing resources (then fix code). - Detect continuously: a scheduled CI job running
terraform plan -detailed-exitcode— exit code 0 = no changes, 1 = error, 2 = changes present → alert. - Prevent: restrict console write access in Terraform-managed accounts, SCPs, tagging
ManagedBy=terraform.
Recovering from state problems
| Problem | Recovery |
|---|---|
| Corrupted/bad state | Restore a previous version from S3 versioning, then plan to verify |
| Stuck lock | Confirm no active run → force-unlock |
| Resource deleted outside Terraform | plan will propose recreating it; or state rm if it should go |
| Resource exists but not in state ("already exists" errors) | import it |
| Wrong address after refactor | moved block |