Runbook: Migrate the State Backend

Purpose

This runbook walks through the migration of Terraform state from one backend to another. The migration is a managed change with a backup, a migrate-state operation, and a verification.

When to use this runbook

Use this runbook when:

• Migrating from local state to a remote backend.
• Migrating between remote backends (e.g. S3 to GCS).
• Migrating between accounts (e.g. dev to prod).
• Migrating to a different region.

Procedure

Step 1: Backup the current state

# For local state
cp terraform.tfstate terraform.tfstate.backup-pre-migration

# For remote state
aws s3 cp \
  s3://mycompany-terraform-state/old-path/terraform.tfstate \
  ./terraform.tfstate.backup-pre-migration

The backup is the recovery.

Step 2: Prepare the new backend

For the S3 backend:

# Create the new bucket
aws s3api create-bucket \
  --bucket mycompany-terraform-state-new \
  --region us-east-1

# Enable versioning
aws s3api put-bucket-versioning \
  --bucket mycompany-terraform-state-new \
  --versioning-configuration Status=Enabled

# Create the lock table (if needed)
aws dynamodb create-table \
  --table-name terraform-locks-new \
  --attribute-definitions AttributeName=LockID,AttributeType=S \
  --key-schema AttributeName=LockID,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

Step 3: Update the backend configuration

Edit versions.tf:

terraform {
  backend "s3" {
    bucket         = "mycompany-terraform-state-new"
    key            = "production/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks-new"
    encrypt        = true
  }
}

Step 4: Run the migration

terraform init -migrate-state

The init:

• Reads the new backend configuration.
• Detects the change from the current backend.
• Copies the state from the current backend to the new backend.
• Updates the local state to point at the new backend.

The output:

Initializing the backend...
Do you want to migrate the existing state to the new backend?
  Pre-existing state was found while migrating the previous
  default workspace to the newly configured "s3" backend.
  An existing non-empty state already exists in the new backend.
  Do you want to copy the existing state to the new backend?
  Enter "yes" to copy and "no" to start with the existing state.

  Enter a value: yes

Type yes to copy the state.

Step 5: Verify the state

terraform state list

The state has the same resources as before.

terraform state show aws_instance.web

The state has the same attributes.

Step 6: Verify the plan

terraform plan

The plan should be empty.

If the plan is non-empty, the state may have been corrupted or the configuration may have drifted. Investigate.

Step 7: Commit to Git

git add versions.tf
git commit -m "Migrate state backend to new bucket"
git push

Step 8: Document the migration

The migration is documented:

• The source backend.
• The destination backend.
• The migration date.
• The verification result.

Verification

The runbook is successful if:

• The state is in the new backend.
• The plan is empty after the migration.
• The next apply is a no-op.
• The migration is documented.

Rollback

If the procedure fails:

• The migration fails. Re-init with the previous backend configuration.
• The state is corrupted. Restore from the backup.

Escalation

Escalate to:

• Engineering manager if the migration fails in production.
• Security team if the credentials are invalid.
• Platform team if the backend is unreachable.