Terraform State Management Guide

# View current state
terraform state list
terraform state show aws_instance.web

terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "production/terraform.tfstate"
    region         = "eu-west-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

# backend-setup/main.tf (run once, locally)
resource "aws_s3_bucket" "state" {
  bucket = "my-terraform-state"
}

resource "aws_s3_bucket_versioning" "state" {
  bucket = aws_s3_bucket.state.id
  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "state" {
  bucket = aws_s3_bucket.state.id
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "aws:kms"
    }
  }
}

resource "aws_s3_bucket_public_access_block" "state" {
  bucket                  = aws_s3_bucket.state.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

resource "aws_dynamodb_table" "locks" {
  name         = "terraform-locks"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"
  attribute {
    name = "LockID"
    type = "S"
  }
}

terraform {
  cloud {
    organization = "my-org"
    workspaces {
      name = "production"
    }
  }
}

Alice: terraform apply → Acquires lock → Makes changes → Releases lock
Bob:   terraform apply → Waits for lock → "Error: state locked by Alice"

terraform force-unlock LOCK_ID

# Define the resource in HCL first
resource "aws_instance" "legacy_server" {
  ami           = "ami-0c1c30571d2dae5c9"
  instance_type = "t3.micro"
}

# Import by resource ID
terraform import aws_instance.legacy_server i-0abc123def456

# Verify
terraform plan  # Should show no changes

# Rename a resource
terraform state mv aws_instance.old_name aws_instance.new_name

# Move into a module
terraform state mv aws_instance.web module.compute.aws_instance.web

# Move between state files
terraform state mv -state-out=other.tfstate aws_instance.web aws_instance.web

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

terraform state rm aws_instance.legacy
# Resource still exists in AWS, but Terraform forgets about it

environments/
  dev/
    main.tf
    backend.tf    → s3://state/dev/terraform.tfstate
  staging/
    main.tf
    backend.tf    → s3://state/staging/terraform.tfstate
  production/
    main.tf
    backend.tf    → s3://state/production/terraform.tfstate

infrastructure/
  network/
    backend.tf    → s3://state/network/terraform.tfstate
  database/
    backend.tf    → s3://state/database/terraform.tfstate
  application/
    backend.tf    → s3://state/application/terraform.tfstate

data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = "my-terraform-state"
    key    = "network/terraform.tfstate"
    region = "eu-west-1"
  }
}

resource "aws_instance" "app" {
  subnet_id = data.terraform_remote_state.network.outputs.private_subnet_id
}

# List state versions
aws s3api list-object-versions --bucket my-terraform-state --prefix production/terraform.tfstate

# Restore a previous version
aws s3api get-object --bucket my-terraform-state \
  --key production/terraform.tfstate \
  --version-id "VERSION_ID" \
  restored-state.tfstate

# Manual backup
terraform state pull > backup-$(date +%Y%m%d).tfstate

# Restore from backup
terraform state push backup-20260301.tfstate