Migration #

# Step 2: Add the backend configuration to providers.tf or backend.tf

# BEFORE (no backend block — using local):
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

# AFTER (with a remote backend):
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

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

# Step 3: Run init with the migrate-state flag
terraform init -migrate-state

# Output:
# Initializing the backend...
# 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. An existing non-empty state already exists
#   in the new backend. The two states have been merged. Please check the output
#   above to ensure this is correct before continuing.
#
#   Enter a value: yes

# Verify the state was successfully moved
terraform state list  # Should show the same resources as before

# Step 6: Delete the local state (after confirming the remote state works)
rm terraform.tfstate terraform.tfstate.backup

# Step 1: Pull the current state locally as a backup
terraform state pull > state-backup-$(date +%Y%m%d-%H%M%S).tfstate

# Step 2: Update the backend configuration to the new backend
# (edit backend.tf)

# Step 3: Run init with migrate-state
terraform init -migrate-state

# Step 4: Verify
terraform plan  # Should be "No changes"

# Step 5: Store the state backup in a safe place
# Don't delete the backup until you're sure the migration succeeded

# HOW TO SPLIT STATE — using terraform state mv

# 1. Prepare a new directory for the compute workspace
mkdir -p environments/production/compute
cd environments/production/compute

# Create the Terraform configuration for compute resources
# (move the relevant resources from the monolithic configuration)

# 2. Initialize the new workspace with a different remote backend
terraform init

# 3. Move resources from the old state to the new state
# (run from the monolithic directory)
cd ../  # back to the monolithic directory

terraform state mv \
  -state-out=compute/terraform.tfstate \
  aws_instance.web[0] \
  aws_instance.web[0]

# For many resources, use a script:
for i in 0 1; do
  terraform state mv \
    -state-out="../compute/terraform.tfstate" \
    "aws_instance.web[$i]" \
    "aws_instance.web[$i]"
done

# 4. Push the modified state to the remote backend
cd ../compute
terraform state push terraform.tfstate

# 5. Verify both workspaces
terraform state list  # compute
cd ../networking
terraform state list  # networking

# ALWAYS back up state before any migration

# Pull the current state
terraform state pull > pre-migration-backup.tfstate

# Verify the backup is readable
cat pre-migration-backup.tfstate | python3 -m json.tool > /dev/null
echo "Backup valid: $?"

# Store it somewhere safe (not just locally)
aws s3 cp pre-migration-backup.tfstate \
  s3://my-backup-bucket/terraform-state-backups/$(date +%Y%m%d-%H%M%S).tfstate

# If the migration produced incorrect state:

# Option 1: Restore from backup
terraform state push pre-migration-backup.tfstate
# WARNING: This overwrites the current state with the backup

# Option 2: Revert the backend configuration
# - Remove or comment out the backend block from the configuration
# - Run terraform init -reconfigure
# - Terraform returns to local state or the previous backend

# Option 3: If using S3 with versioning enabled
# Restore the previous version from the S3 console or CLI
aws s3api list-object-versions \
  --bucket my-terraform-state \
  --prefix production/terraform.tfstate

aws s3api get-object \
  --bucket my-terraform-state \
  --key production/terraform.tfstate \
  --version-id VERSION_ID \
  restored-state.tfstate

# STATE MIGRATION PRE-CHECKLIST:

# 1. Back up the current state
terraform state pull > backup-$(date +%Y%m%d-%H%M%S).tfstate
ls -la backup-*.tfstate  # Verify the file exists and has a reasonable size

# 2. Make sure there are no pending changes
terraform plan
# Should be "No changes" — if not, apply first or resolve

# 3. Make sure there's no active lock
terraform state pull  # If it succeeds, there's no lock

# 4. Verify nobody is currently working
# Check CI/CD pipelines, communicate with the team

# 5. Prepare a rollback plan
cp backup-*.tfstate emergency-rollback.tfstate

# Scenario: Moving from local to S3

# 1. Configure the new backend (not yet initialized)
terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "prod/terraform.tfstate"
    region = "ap-southeast-1"
  }
}

# 2. Run init — Terraform will detect the backend changed
terraform init
# Output: "Backend configuration changed. Do you want to copy existing state?"
# Answer: yes

# 3. Terraform automatically copies state from local to S3
# 4. Verify: terraform plan should be "No changes"

# ROLLBACK if there's a problem:
# 1. Change the backend config back to local
# 2. Run terraform init
# 3. Copy the state backup to the local directory

# The state file contains ALL resource information:
# - IDs, ARNs, IP addresses
# - Passwords, API keys (if defined in Terraform)
# - Every attribute of every managed resource

# DON'T:
# - Commit state to Git
# - Store it on a local filesystem for production
# - Share state files without encryption

# MUST:
# - Store in an encrypted backend (S3+KMS, GCS, TFC)
# - Enable access logging
# - Restrict IAM access (only CI/CD roles)