terraform-state-manager

Terraform State Manager

This skill provides safe workflows for Terraform state operations and troubleshooting.

When to Use

Use this skill when:

• Importing existing infrastructure into Terraform
• Moving resources to different addresses (renaming)
• Removing resources from state without destroying them
• Migrating state between backends (local to S3, etc.)
• Recovering from state corruption or conflicts
• Splitting or merging state files

Critical Safety Rules

ALWAYS follow these rules when working with state:

1. Backup first: Create state backup before any operation
2. Plan after: Run terraform plan after state changes to verify
3. One at a time: Make incremental changes, not bulk operations
4. Test in non-prod: Practice state operations in dev/test first
5. Version control: Commit code changes with state operations

Common Operations

1. Import Existing Resources

Workflow:

# Step 1: Write the resource configuration in .tf file
# Step 2: Import the resource
terraform import <resource_address> <resource_id>

# Step 3: Verify with plan (should show no changes)
terraform plan

Example - Import AWS S3 Bucket:

# 1. Add to main.tf
resource "aws_s3_bucket" "existing" {
  bucket = "my-existing-bucket"
}

# 2. Import
terraform import aws_s3_bucket.existing my-existing-bucket

# 3. Verify
terraform plan  # Should show: No changes

Tips:

• Find resource ID format in provider docs
• Import one resource at a time
• Some resources require multiple imports (bucket + versioning + encryption)
• Use terraform show to see imported attributes

2. Move Resources (Rename/Refactor)

Workflow:

# Move resource to new address
terraform state mv <source> <destination>

# Verify
terraform plan  # Should show: No changes

Example - Rename Resource:

# Before: aws_s3_bucket.bucket
# After:  aws_s3_bucket.main

terraform state mv aws_s3_bucket.bucket aws_s3_bucket.main

Example - Move to Module:

# Move resource into module
terraform state mv aws_instance.web module.web_server.aws_instance.main

Example - Move Between Modules:

terraform state mv module.old.aws_db_instance.main module.new.aws_db_instance.main

Tips:

• Update .tf files to match new addresses before running plan
• Use quotes for addresses with special characters
• Move related resources together (e.g., bucket + bucket_policy)

3. Remove from State

Workflow:

# Remove resource from state (keeps actual resource)
terraform state rm <resource_address>

# Verify resource still exists in cloud
# Update .tf files to remove resource definition

Example - Remove Resource:

# Remove from Terraform management
terraform state rm aws_s3_bucket.temp

# Resource still exists in AWS, just not managed by Terraform

Use cases:

• Handing off resource to another Terraform workspace
• Removing accidentally imported resources
• Decomissioning Terraform management of legacy resources

4. Migrate State Backend

Workflow for Local → S3:

# Step 1: Create S3 bucket and DynamoDB table for locking

# Step 2: Add backend configuration
terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "project/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

# Step 3: Initialize with migration
terraform init -migrate-state

# Step 4: Verify
terraform plan

Backend Migration Checklist:

• Backup current state file
• Create new backend resources (S3 bucket, etc.)
• Update backend configuration in code
• Run terraform init -migrate-state
• Verify with terraform plan
• Test state locking works
• Update team documentation

5. List State Resources

View all resources in state:

# List all resources
terraform state list

# Show specific resource details
terraform state show aws_s3_bucket.main

# Output state as JSON
terraform show -json

Troubleshooting

State Lock Issues

# If state is locked and shouldn't be
terraform force-unlock <lock-id>

# Only use if you're certain no other operation is running

State Drift Detection

# Check for drift between state and actual infrastructure
terraform plan -refresh-only

# Update state to match reality (doesn't change infrastructure)
terraform apply -refresh-only

Corrupted State Recovery

# Terraform keeps backups automatically
ls terraform.tfstate.backup

# Restore from backup
cp terraform.tfstate.backup terraform.tfstate

# Or restore from remote backend version history (S3 versioning)

Pre-Operation Checklist

Before any state operation:

• Backup state file (cp terraform.tfstate terraform.tfstate.backup)
• Ensure no other operations are running
• Understand the exact command and its impact
• Have rollback plan ready
• Test in non-production first

Post-Operation Verification

After any state operation:

• Run terraform plan (should show expected changes or no changes)
• Verify resource still exists in cloud console
• Check state file size is reasonable
• Commit changes to version control
• Document what was done and why