Plain language
Drift is any difference between real infrastructure and state, caused by changes made outside Terraform: console edits, scripts, or other tools. A normal plan refreshes first, so it detects drift. It reports "Objects have changed outside of Terraform," then proposes changes that bring reality back in line with the configuration.
Ways to respond to drift
| Goal | Action |
|---|---|
| Revert reality to match the code | terraform apply. The plan proposes undoing the manual change. |
| Keep the manual change permanently | Update the configuration to match, then plan shows no changes. Optionally run apply -refresh-only first to record it. |
| Record reality in state, and review it first | terraform plan -refresh-only, then terraform apply -refresh-only |
| Let another system own an attribute long-term | lifecycle { ignore_changes = [attr] } (Module 4) |
If an object is deleted outside Terraform, refresh removes it from state, and the plan proposes creating it again.
Changing state safely
| Need | Preferred: config-driven, plannable, reviewable | CLI alternative: immediate, no plan |
|---|---|---|
| Rename or move a resource (including into a module) | moved { from = … to = … } |
terraform state mv SRC DEST |
| Stop managing a resource without destroying it | removed { from = … lifecycle { destroy = false } } (1.7+) |
terraform state rm ADDR |
| Bring an existing object under management | import block (Module 7) |
terraform import |
| Force recreation | terraform apply -replace=ADDR |
terraform taint (deprecated) |
Config-driven blocks are preferred because they appear in the plan, go through code review, and work in HCP Terraform, where you might not have direct CLI access to state.
moved {
from = local_file.old_name
to = local_file.new_name
}
removed {
from = local_file.legacy
lifecycle {
destroy = false # keep the real object; just forget it
}
}Always set destroy explicitly in removed blocks so the intent is unmistakable to reviewers. destroy = true destroys the object as the block is removed. Remove the resource's own resource block in the same change. After the change is applied everywhere, you can delete moved and removed blocks, but shared modules often keep moved blocks so that every caller can upgrade.
Why manual state edits are discouraged
- State JSON includes a
serialand alineage. Hand edits can conflict with them, or be rejected. - Hand edits bypass locking and leave no review trail.
terraform state pullandterraform state pushexist for disaster recovery, butpushcan overwrite good state. Use them only as a last resort.