jidohyun/terraform-state-manager

Terraform State Manager

This skill guides you through safe Terraform state manipulation operations.

When to Use

• Importing existing cloud resources into Terraform management (terraform import)
• Renaming resources or moving them into/out of modules (terraform state mv)
• Removing resources from Terraform control without destroying them (terraform state rm)
• Migrating state between backends (e.g., local to GCS/S3)
• Fixing state locks or corruption

Critical Safety Rules

[!IMPORTANT] ALWAYS follow these rules to prevent data loss or service downtime.

1. Backup First: Create a backup of your state file (.tfstate) before ANY operation.

   terraform state pull > backup.tfstate
   

2. Plan After: Run terraform plan immediately after any state change to verify the result is a "no-op" (no changes detected) or matches expectation.
3. One by One: Perform operations incrementally rather than in bulk.
4. Communicate: Ensure no one else is running Terraform during maintenance.

Common Operations

1. Importing Resources

Use when you have a resource in the cloud but not in Terraform state.

1. Write Config: Create the resource block in your .tf files.
2. Import:

   terraform import <resource_address> <cloud_id>
   # Example: terraform import google_storage_bucket.my_bucket my-project-bucket-name
   

3. Verify: Run terraform plan. It should be empty or show only minor metadata updates.

2. Moving Resources (Refactoring)

Use when renaming resources or moving them into modules.

terraform state mv <source_address> <destination_address>
# Example: terraform state mv google_storage_bucket.old_name module.storage.google_storage_bucket.new_name

3. Removing Resources

Use when you want to stop managing a resource with Terraform but keep it running.

terraform state rm <resource_address>

4. Migrating Backend

Use to change where state is stored.

1. Update Config: Change the backend block in versions.tf or backend.tf.
2. Migrate:

   terraform init -migrate-state
   

   Answer "yes" to copy the state to the new location.

Troubleshooting

• State Lock: If a process crashed and left a lock:

  terraform force-unlock <LOCK_ID>
  

  Warning: Be absolutely sure no other process is running.