terraform-state-manager_skill

Overview

This skill manages Terraform state operations such as importing existing resources, moving resources between addresses or modules, removing resources from state without destroying them, and migrating state backends. It provides step-by-step commands and safety guardrails to refactor state safely in production environments. Use it to fix state drift, migrate backends, or reorganize resource layouts without unintended downtime.

How this skill works

The skill describes the precise Terraform CLI commands and workflow for common state tasks: terraform import, terraform state mv, terraform state rm, and terraform init -migrate-state. It emphasizes pre- and post-operation verification steps like pulling a backup of the .tfstate file and running terraform plan to confirm no unexpected changes. It also covers handling state locks and safe unlock procedures with terraform force-unlock when appropriate.

When to use it

• Import existing cloud resources that aren’t yet in Terraform state
• Refactor resources by renaming or moving them into or out of modules
• Remove resources from Terraform control while leaving the infrastructure intact
• Migrate state storage from local files to remote backends such as GCS or S3
• Recover from state corruption or stalled locks preventing Terraform runs

Best practices

• Always create a state backup before any operation: terraform state pull > backup.tfstate
• Perform operations one at a time and validate with terraform plan after each change
• Ensure no one else is running Terraform; coordinate maintenance windows
• Use versioned remote backends for production state and enable locking when supported
• Document each state change in changelogs or runbooks to aid audits and rollbacks

Example use cases

• Import an existing Cloud Storage bucket into Terraform to begin lifecycle management
• Move a resource into a module after refactoring to keep addresses stable for other resources
• Remove a manually managed VM from state while preserving the VM itself
• Migrate state from a local file to a GCS backend during team onboarding
• Force-unlock state after a CI crash to restore normal deployment workflows