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:
-
Backup first: Create state backup before any operation
-
Plan after: Run terraform plan after state changes to verify
-
One at a time: Make incremental changes, not bulk operations
-
Test in non-prod: Practice state operations in dev/test first
-
Version control: Commit code changes with state operations
Common Operations
- 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
- 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)
- 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
- 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
- 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