- You renamed a resource in code (for example,
aws_instance.web→aws_instance.webserver). - You reorganized files or modules and moved resources between them.
- You want to adopt existing, manually-created infrastructure into Terraform management.
- You want to stop managing a resource with Terraform while leaving the real resource running.

Why configuration-driven refactoring?
Historically you would run CLI state commands such asterraform state mv, terraform state rm, and terraform import. Those work, but they happen outside of your configuration and are not recorded in version control. That leads to:
- No Git history for state changes (hard to audit or review).
- Risk of manual mistakes editing the state file.
- Lack of previewability in the normal plan/apply workflow.
.tf files: moved, removed, and import. Because these are code, they are:
- Trackable in Git and visible in PRs.
- Previewable with
terraform plan. - Applied consistently via
terraform apply.
Core refactoring blocks
Place these blocks inside your Terraform configuration (for example, in a
.tf file that you commit to source control).
Example refactoring blocks:
Important details and best practices
moved: Prevents Terraform from destroying and recreating the resource by mapping the old state address to the new one.removed: Removes an address from the state file without causing a destroy. If you simply delete a resource’s configuration without aremovedblock, Terraform will plan to destroy that resource on next apply.import: Adopts an existing resource by mapping the cloud/provider ID (id) to a Terraform resource address (to). The ID format is provider-specific—consult the provider docs for exact formats.
lifecycle.prevent_destroy as a guard if you want to avoid accidental destruction while refactoring:
Always back up your state file before performing refactors, especially when running legacy
terraform state or terraform import commands. Configuration-driven refactors are safer, but you should still validate plans in a non-production environment first.Typical workflow
- Add a
moved,removed, orimportblock to your Terraform code and commit it to version control. - Run
terraform planto preview the state-only changes (validate what will be updated in state). - Run
terraform applyto update the state. The real resources remain unchanged unless you intentionally modify them.
Refactoring blocks let you manage state changes with the same safety and reviewability as other Terraform code. Always use
terraform plan to preview the impact before applying.Hands-on demos and scenarios
The three blocks (moved, removed, import) cover the majority of real-world state refactoring situations:
- moved — Safely rename and relocate resources without destroying them.
- removed — Stop managing a resource while keeping it running in the cloud.
- import — Adopt manually created infrastructure into Terraform state.
- Test in a non-production workspace first.
- Commit refactor blocks in a dedicated PR so reviewers can verify the intent.
- Maintain clear commit messages describing why the refactor was required.
Links and references
- Terraform CLI - state commands
- Terraform import documentation
- HashiCorp Certified: Terraform Associate