Renaming a Terraform resource seems harmless. In practice, it can trigger infrastructure destruction.
Terraform identifies resources by state address, not by whether two resources look similar. If you rename a resource label, Terraform interprets that change as one object disappearing and a new one appearing. The plan will show a destroy and recreate operation even if the underlying infrastructure should stay the same.
Two mechanisms exist to prevent that churn.
terraform state mv rewrites the state mapping directly. It tells Terraform that the existing object should now be tracked under a new address. This works immediately, but the change often happens outside version control. Other engineers or CI pipelines cannot see the refactor intent. They only see the resulting state.
The moved block solves this governance gap. Instead of editing state manually, the address migration is declared in configuration. Terraform reads that instruction during planning and rewrites the mapping during apply. The result is a reviewable and repeatable refactor across every environment.
Both tools solve the same technical problem. The difference is operational discipline.
Manual state edits are quick repairs. Declarative refactors are durable engineering.
The lesson explores the mechanisms behind both approaches and shows how to refactor Terraform safely without recreating infrastructure.
Watch the full lesson on YouTube.