Migrate State Between Backends

Advanced15 minTrending

Move Terraform state from local to remote backend (S3, GCS, Azure) safely for team collaboration and disaster recovery.

Prerequisites

-Terraform installed
-Remote backend bucket/container created
-Cloud provider credentials configured

Steps

Back up the current state file

Create a local backup of your state file before making any changes to the backend configuration.

$ cp terraform.tfstate terraform.tfstate.backup

Always keep a backup. If the migration fails, you can restore from this copy.

Add the remote backend configuration

Define the new backend block in your Terraform configuration pointing to the remote storage location.

$ cat <<'EOF' > backend.tf terraform { backend "s3" { bucket = "my-tf-state" key = "prod/terraform.tfstate" region = "us-east-1" dynamodb_table = "tf-lock" encrypt = true } } EOF

Use a DynamoDB table for state locking to prevent concurrent modifications.

Initialize with migration flag

Run terraform init with the -migrate-state flag. Terraform detects the backend change and prompts to copy existing state.

$ terraform init -migrate-state

Answer 'yes' when prompted. If you answer 'no', your state will not be migrated and you may lose track of managed resources.

Verify state in remote backend

List all resources to confirm the state was migrated correctly and all resources are accounted for.

$ terraform state list

Run a plan to confirm no changes

Execute a plan to ensure Terraform sees no differences between state and infrastructure after migration.

$ terraform plan

A clean plan with 0 changes confirms the migration was successful.

Remove the local state file

Delete the local terraform.tfstate now that state lives in the remote backend. Keep the backup for a few days.

$ rm terraform.tfstate terraform.tfstate.backup

Only delete local state after you have confirmed the remote backend is working correctly.

Full Script

full-script.sh

#!/bin/bash
set -euo pipefail

# Terraform State Migration Script
# Migrates local state to an S3 remote backend

STATE_BUCKET="${1:?Usage: $0 <bucket-name> <dynamodb-table> <region>}"
LOCK_TABLE="${2:?Usage: $0 <bucket-name> <dynamodb-table> <region>}"
REGION="${3:-us-east-1}"

echo "==> Backing up current state..."
cp terraform.tfstate terraform.tfstate.backup 2>/dev/null || echo "No local state file found"

echo "==> Writing backend configuration..."
cat > backend.tf <<EOF
terraform {
  backend "s3" {
    bucket         = "$STATE_BUCKET"
    key            = "prod/terraform.tfstate"
    region         = "$REGION"
    dynamodb_table = "$LOCK_TABLE"
    encrypt        = true
  }
}
EOF

echo "==> Initializing with migration..."
terraform init -migrate-state -input=false

echo "==> Verifying state..."
terraform state list

echo "==> Running plan to confirm no drift..."
terraform plan -detailed-exitcode || {
  if [ $? -eq 2 ]; then
    echo "WARNING: Plan shows changes. Review before proceeding."
    exit 1
  fi
}

echo "==> Migration complete. Remote backend is active."
echo "    Backup saved at terraform.tfstate.backup"

FAQ

Discussion

Loading comments...

#!/bin/bash set -euo pipefail # Terraform State Migration Script # Migrates local state to an S3 remote backend STATE_BUCKET="${1:?Usage: $0 <bucket-name> <dynamodb-table> <region>}" LOCK_TABLE="${2:?Usage: $0 <bucket-name> <dynamodb-table> <region>}" REGION="${3:-us-east-1}" echo "==> Backing up current state..." cp terraform.tfstate terraform.tfstate.backup 2>/dev/null || echo "No local state file found" echo "==> Writing backend configuration..." cat > backend.tf <<EOF terraform { backend "s3" { bucket = "$STATE_BUCKET" key = "prod/terraform.tfstate" region = "$REGION" dynamodb_table = "$LOCK_TABLE" encrypt = true } } EOF echo "==> Initializing with migration..." terraform init -migrate-state -input=false echo "==> Verifying state..." terraform state list echo "==> Running plan to confirm no drift..." terraform plan -detailed-exitcode || { if [ $? -eq 2 ]; then echo "WARNING: Plan shows changes. Review before proceeding." exit 1 fi } echo "==> Migration complete. Remote backend is active." echo " Backup saved at terraform.tfstate.backup"