State Management & Infrastructure Maintenance

Default State Storage

When no backend block is configured, Terraform defaults to the local backend. State is written to terraform.tfstate in the working directory. A backup copy (terraform.tfstate.backup) is created before each state update so you can recover from a failed apply.

• State file is plain JSON — contains resource attributes, including secrets
• No built-in locking — two concurrent applies can corrupt state
• Not practical for teams — each developer has their own local copy
• Always .gitignore state files: they contain sensitive data (passwords, private keys)
• Suitable for learning and solo development only

Why Locking Matters

Without locking, two engineers running terraform apply simultaneously can interleave writes and corrupt the state file. Terraform automatically acquires a lock before any operation that modifies state: apply, destroy, state mv, and others.

• Local backend: does NOT lock by default
• S3 backend: requires a DynamoDB table — add dynamodb_table = "terraform-locks" to the backend block
• HCP Terraform / Terraform Cloud: built-in locking, no extra config needed
• GCS, AzureRM: native locking support via blob leases / GCS locks
• Not all backends support locking — check provider docs

force-unlock

If Terraform crashes mid-apply, it may leave a stale lock. Use terraform force-unlock <lock-id> to manually release it. The lock ID is displayed in the error message when a lock cannot be acquired.

• Use with caution — only release a lock when you are certain no other process holds it
• The lock ID is a UUID generated at lock acquisition time
• Running force-unlock on an active lock can corrupt state

S3 Backend Configuration

The most common remote backend on the exam. The backend block lives inside the terraform {} block:

terraform {
  backend "s3" {
    bucket         = "my-tf-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

• bucket: S3 bucket name (must exist before init)
• key: path within bucket (use workspace-aware paths in multi-env setups)
• dynamodb_table: enables state locking via DynamoDB
• encrypt = true: enables server-side encryption of state

Common Backends

Init Flags for Backend Changes

• terraform init -reconfigure: re-initializes the backend without migrating state; use when you change backend config but DON'T want to migrate existing state
• terraform init -migrate-state: migrates state from the old backend to the new backend configuration
• Partial configuration: sensitive values (credentials, tokens) can be omitted from the backend block and supplied via -backend-config="key=value" CLI flags or env vars at init time — keeps secrets out of VCS

Detecting and Resolving Drift

Drift occurs when someone manually changes infrastructure outside of Terraform (e.g., resizing an instance in the AWS console). Terraform state no longer matches reality.

• terraform plan: highlights drift as differences between state and provider-reported attributes
• terraform apply -refresh-only: updates state to match real infrastructure WITHOUT making any infrastructure changes — replaces the deprecated terraform refresh command
• terraform refresh: deprecated in Terraform 1.x; always prefer -refresh-only flag

The moved Block

When you rename a resource in your config, Terraform would normally destroy the old one and create a new one. The moved block records the rename so Terraform updates state without recreating the resource:

moved {
  from = aws_instance.old_name
  to   = aws_instance.new_name
}

• Works for module moves too: from = aws_instance.foo → to = module.web.aws_instance.foo
• Can be committed and then removed in a follow-up PR once all state is updated
• Does NOT destroy or recreate the resource

The removed Block (Terraform 1.7+)

Removes a resource from Terraform state management without destroying the actual cloud resource:

removed {
  from = aws_instance.example
  lifecycle {
    destroy = false
  }
}

• destroy = false: Terraform stops tracking the resource but leaves it running
• destroy = true (default if omitted): destroys the resource and removes from state
• Useful when handing off a resource to another team's Terraform config

State CLI Commands

Key distinction: terraform state rm stops Terraform from managing a resource — it does NOT call the provider's destroy API. The resource keeps running. To actually delete the resource, use terraform destroy.

Modern: import Block (Terraform 1.5+)

The recommended approach. Declare an import block in your config:

import {
  to = aws_instance.example
  id = "i-1234567890abcdef0"
}

• Run terraform plan to preview the import, then terraform apply to execute
• Add -generate-config-out=generated.tf to terraform plan — Terraform auto-generates the resource block (experimental but useful)
• After applying, remove the import block — it's a one-time operation
• Import ID format varies by resource type — always check the provider documentation

Legacy: terraform import CLI Command

terraform import aws_instance.example i-1234567890abcdef0

• Requires writing the resource block in config before running the command
• Does NOT auto-generate config — you must manually write all attributes
• Imports directly into state; subsequent plan may show drift if config is incomplete
• Still valid and supported but the import block approach is preferred

State Inspection Commands

• terraform state list: lists all resource addresses tracked in state; use -id=<real-resource-id> to filter by actual provider resource ID
• terraform state show <address>: prints all attributes of a single resource in human-readable form
• terraform state pull: downloads and prints the current state as raw JSON to stdout — useful for scripting or manual inspection
• terraform state push <file>: manually uploads a state file to the remote backend — overwrites remote state, use with extreme caution
• terraform show: shows the current state (or a saved plan) in human-readable form
• terraform show terraform.tfplan: shows the contents of a saved plan file

TF_LOG Environment Variable

Set TF_LOG before running any Terraform command to enable detailed logging output to stderr:

• TF_LOG=TRACE terraform apply — maximum logging to stderr
• TF_LOG_PATH=/tmp/terraform.log — redirects logs to a file (in addition to or instead of stderr)
• TF_LOG_CORE — sets log level for Terraform core separately
• TF_LOG_PROVIDER — sets log level for provider plugins separately
• TF_LOG="" — disables logging entirely
• crash.log: auto-generated in the working directory on a Terraform panic — always include when filing bug reports with HashiCorp