Skip to main content
Now that you can inspect state, detect drift, and remediate it, the next skill is actively refactoring your Terraform state. State refactoring reorganizes how Terraform tracks resources without changing the actual infrastructure. Common scenarios requiring state refactoring:
  • 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.
Without explicit refactoring, Terraform treats code reorganizations as destructive: it assumes the old address was removed and a new one created, which can lead to destroy/create operations on real infrastructure unless you instruct Terraform otherwise.
A presentation slide titled "State Refactoring" explaining how to reorganize how Terraform tracks infrastructure, including a bulleted list of common scenarios (renaming resources, reorganizing modules, adopting existing infrastructure, and stopping management). The slide also shows the Terraform logo.

Why configuration-driven refactoring?

Historically you would run CLI state commands such as terraform 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.
To solve this, Terraform provides configuration-driven refactoring blocks that you declare directly in .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.
For the HashiCorp Certified: Terraform Associate exam and real-world use, be familiar with both the legacy CLI state commands and the modern configuration-driven approach.

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 a removed block, 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.
Use lifecycle.prevent_destroy as a guard if you want to avoid accidental destruction while refactoring:
This pattern is useful when you plan to remove a resource from configuration but want to ensure Terraform cannot accidentally destroy it during the refactor.
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

  1. Add a moved, removed, or import block to your Terraform code and commit it to version control.
  2. Run terraform plan to preview the state-only changes (validate what will be updated in state).
  3. Run terraform apply to update the state. The real resources remain unchanged unless you intentionally modify them.
Common commands:
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.
When practicing these techniques:
  • 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.

Watch Video