Opscraft
Terraform · Lesson 4 of 12 · 8 min read

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:

Enlarge diagramaws_instance.webin main.tfterraform.tfstateid, ARN, IPs, allattributesi-0abc1234the real EC2 instanceLose the state and Terraform forgets the instance; it keeps running, unmanaged.
Figure 1. State is the map between each block in your code and the real resource it created, including every attribute (and any secrets).
Swipe sideways to see all of it, or tap to open it full screen.
  • 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:

Enlarge diagramS3 STATE BUCKETengineer laptopplan / applyCI pipelineplan / applyprod/network/terraform.tfstatelock fileone run at a timeversioning onSSE-KMSpublic access blockedIAM-restricted
Figure 2. A team setup on AWS: everyone, including CI, uses one remote state in S3, protected and locked.
Swipe sideways to see all of it, or tap to open it full screen.
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.tfbackend at init.

Other backends: HCP Terraform / Terraform Enterprise (remote runs, state, policy), GCS, azurerm, Kubernetes, PostgreSQL. OpenTofu adds client-side state encryption.

Locking in practice

Enlarge diagramAshaterraform applyState lockBalaterraform planacquire lock: OKacquire lockerror: lock held by Ashaapply done, release lockretry: OK
Figure 3. Locking stops two runs writing the same state at once.
Swipe sideways to see all of it, or tap to open it full screen.

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.

Enlarge diagramWithout movedWith moved { from, to }aws_instance.web: destroyaws_instance.app: createDowntime, new IP, lost dataState entry renamedPlan: 0 to add, 0 to destroyThe real instance is untouched
Figure 4. Renaming in code looks like destroy-and-create to Terraform. A moved block tells it the resource just changed address.
Swipe sideways to see all of it, or tap to open it full screen.

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.

Enlarge diagramFind the IDbucket name,instance id…import blockto = address, id =real IDWrite theconfigby hand, or letplan generate itplantune until 0changesapplynow Terraformmanages it12345
Figure 5. Importing: write the block, point Terraform at the existing resource, then plan until it shows no changes.
Swipe sideways to see all of it, or tap to open it full screen.

Drift

Drift = real infrastructure changed outside Terraform (console edits, scripts, other tools). plan reveals it. Options:

Enlarge diagramconsole changeopens port 22 on asecurity groupterraform planshows ~ update toremove itRevertapply: code winsAcceptupdate the code to matchDetectnightly plan -detailed-exitcode
Figure 6. Drift: someone changes a resource outside Terraform. The next plan shows it, and you decide which side wins.
Swipe sideways to see all of it, or tap to open it full screen.
  • 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-only updates 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