Local #

{
  "version": 4,
  "terraform_version": "1.6.3",
  "serial": 12,
  "lineage": "a3b4c5d6-e7f8-9012-abcd-ef1234567890",
  "outputs": {
    "instance_public_ip": {
      "value": "54.123.45.67",
      "type": "string"
    }
  },
  "resources": [
    {
      "mode": "managed",
      "type": "aws_instance",
      "name": "web",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "instances": [
        {
          "schema_version": 1,
          "attributes": {
            "ami": "ami-0abcdef1234567890",
            "id": "i-0abcdef1234567890",
            "instance_type": "t3.micro",
            "private_ip": "10.0.1.42",
            "public_ip": "54.123.45.67",
            "subnet_id": "subnet-0abcdef1234",
            "tags": {
              "Name": "web-server",
              "Environment": "production"
            }
          }
        }
      ]
    }
  ]
}

# Examples of state contents containing sensitive data:

# aws_db_instance stores passwords in state:
# "password": "super-secret-db-password-123"

# aws_iam_access_key stores the secret key:
# "secret": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

# tls_private_key stores the private key:
# "private_key_pem": "-----BEGIN RSA PRIVATE KEY-----\n..."

# Make sure .gitignore already excludes state files:
cat .gitignore

# Local .terraform directories
**/.terraform/*

# State files
*.tfstate
*.tfstate.*

# List all resources
terraform state list

# View details of a specific resource
terraform state show aws_instance.web

# Remove a resource from state (without destroying the resource in the cloud)
terraform state rm aws_instance.web

# Move/rename a resource in state
terraform state mv aws_instance.web aws_instance.web_server

# Pull state to stdout (useful for backup or inspection)
terraform state pull > backup-$(date +%Y%m%d).tfstate

# Push state from a file (careful — can overwrite the active state)
terraform state push backup-20240101.tfstate

# Serial: a sequence number that increments every time state is modified
# You can see the serial from the state file:
cat terraform.tfstate | jq '.serial'
# Output: 12

# Every successful terraform apply increments the serial:
# first apply → serial: 1
# second apply   → serial: 2
# etc.

# If two people apply simultaneously (without locking), both
# read serial 12. The first to write → serial 13.
# The second also writes → serial 13 (overwriting the first).
# The data from the first apply is lost.

# Lineage: a UUID created once when the state is first initialized
cat terraform.tfstate | jq '.lineage'
# Output: "a3b4c5d6-e7f8-9012-abcd-ef1234567890"

# Lineage is used during terraform state push to verify
# that the pushed file comes from the same workspace:
terraform state push wrong-state.tfstate
# Error: lineage mismatch — the state comes from a different workspace

# This prevents incidents: a developer accidentally pushing state
# from the staging environment to the production environment

# Find a specific resource in the state file
cat terraform.tfstate | jq '.resources[] | select(.name=="web")'
# Shows all stored data of aws_instance.web

# Check a specific attribute of a resource
cat terraform.tfstate | jq '.resources[]
  | select(.type=="aws_instance" and .name=="web")
  | .instances[0].attributes.public_ip'
# Output: "54.123.45.67"

# Count the number of managed resources
cat terraform.tfstate | jq '[.resources[].instances[]] | length'
# Output: 7 (meaning 7 resource instances in state)

# List all resource types in state
cat terraform.tfstate | jq '[.resources[].type] | unique'
# Output: ["aws_instance", "aws_security_group", "aws_subnet", ...]

# Check for resources containing sensitive data
cat terraform.tfstate | jq '.. | .password? // .secret? // .private_key_pem?
  | select(. != null)' 2>/dev/null
# Output: a list of sensitive values stored in plaintext
# THIS is why state must never be committed to Git

# STEP 1: Back up the state before migrating
cp terraform.tfstate terraform.tfstate.backup.before-migration

# STEP 2: Create the remote backend (e.g. S3)
# Add the backend configuration to main.tf or backend.tf:

terraform {
  backend "s3" {
    bucket         = "my-terraform-state-bucket"
    key            = "project/terraform.tfstate"
    region         = "ap-southeast-1"
    encrypt        = true
    dynamodb_table = "terraform-state-lock"
  }
}

# STEP 3: Run terraform init to migrate
terraform init
# Terraform detects that the backend changed from local to S3
# and offers to move the state:
#
# "Do you want to copy existing state to the new backend?
#   Pre-existing state was found while migrating the previous
#   "local" backend to the newly configured "s3" backend."
#
# Choose "yes" — Terraform will:
# 1. Read the local state
# 2. Upload it to S3
# 3. Delete the local state (after success)

# STEP 4: Verify the state was successfully moved
terraform state list
# All resources must appear — if empty, something's wrong

# STEP 5: Verify the plan doesn't show changes
terraform plan
# "No changes" — the state is in sync with the remote

# PITFALL 1: Deleting the .terraform/ directory
rm -rf .terraform/
terraform plan
# Error: Backend not initialized
# Solution: terraform init (will re-download providers and re-init the backend)

# PITFALL 2: Moving the state file to another computer without .terraform/
# → The other developer doesn't know which backend is used
# → Always include instructions: "Run terraform init first"

# PITFALL 3: Two terminals running terraform apply simultaneously
# Terminal 1: terraform apply → reads state serial 10
# Terminal 2: terraform apply → reads state serial 10 (same!)
# Terminal 1: done → writes state serial 11
# Terminal 2: done → writes state serial 11 (overwriting terminal 1!)
# → Terminal 1's state is lost
# → Local state has no locking to prevent this

# PITFALL 4: State file corrupted due to a full disk or a killed process
# If terraform apply is killed mid-way through writing state:
cat terraform.tfstate
# Output: incomplete JSON — Terraform errors when reading
# Solution: restore from terraform.tfstate.backup

# PITFALL 5: Confusing workspace switching
terraform workspace new staging
# Staging state is separate, but stored in .terraform.tfstate.d/
# Developers often forget which workspace they're in
# Solution: show the workspace in the shell prompt (see the workspace article)