Terraform Imports, Refactors, and Recovery: Plan First

Terraform Imports, Refactors, and Recovery

Terraform imports, refactors, and recovery change the relationship between configuration, state, and real infrastructure. Begin by identifying which relationship is wrong. Import adopts an existing object into management; a refactor changes its configuration address; recovery repairs the state record after a failure. Treating all three as “fix state” hides the operation's actual consequences.

For production work, establish the correct backend, workspace, credentials, resource identity, and change authority before modifying anything. The example here is source-reviewed HCL only. No Terraform CLI, provider, backend, import, apply, or state-write operation was executed.

TL;DR

Identify the real object, its current management owner, and its intended address.
Write configuration that describes the intended retained infrastructure.
Use documented import or moved-block mechanisms for the actual task.
Review the complete resulting plan for unintended changes.
Preserve recovery evidence and investigate locks before overriding protection.

Quick Example

This illustrative address change declares that an existing bucket's Terraform address is being renamed. The original resource configuration must also be represented under the intended new address.

The block communicates an address relationship; it does not prove that the rest of the configuration preserves the object. A change to another argument could still cause an update or replacement. Review the entire actual plan with the installed Terraform and provider versions before authorizing execution.

Core Concepts

HashiCorp documents import blocks that identify existing infrastructure and a corresponding destination resource configuration. Importing an object does not replace the need for correct configuration or an appropriate plan review. Terraform import overview.

Moved blocks record address changes so Terraform can associate existing state with the new address. Removing historic move declarations can be a breaking change for consumers that still need that path. Terraform refactoring.

State is a management record, not a complete copy of the running infrastructure. Restoring a state snapshot does not undo real changes made after it was captured. Recovery must reconcile the record with the current world.

Choose the operation from the mismatch

This editorial matrix is a planning aid, not permission to execute state operations. An uncertain owner or an unexplained destructive action is a reason to stop the change and resolve the mismatch.

Adopt and refactor with reviewable intent

For adoption, identify the resource through the provider's documented import identity and confirm that another configuration does not already manage it. Record which team owns future changes. Two configurations competing over one real object can create a recurring operational conflict.

Match configuration to the intended retained behavior. Provider defaults and attributes discovered during import can expose differences that were previously unmanaged. Distinguish deliberate normalization from accidental changes and review each proposed action.

For refactors, preserve resource identity while changing organization deliberately. Address changes involving modules, instance keys, or counts need exact mappings. Test the supported upgrade path in an authorized environment with representative state before publishing a reusable module change.

Do not equate “no delete” with “no risk.” An in-place update can alter access, networking, retention, or application behavior. Review the semantic impact and unknown values as well as the action labels.

Recover without confusing history and reality

HashiCorp warns that manually pushing state overwrites remote state and describes lineage and serial checks intended to prevent certain mistaken overwrites. Backend locking support varies. Its recovery guidance also warns against unlocking before understanding why a lock remained. State storage and locking, state recovery.

Preserve the relevant current state, recovery artifacts, change records, and backend version history through the approved process. State can contain sensitive values, so storage and access need protection. Do not paste a full state file into a general chat or ticket to make diagnosis convenient.

Reconstruct what happened: which run started, what infrastructure changed, where persistence failed, and whether another run has since modified the same scope. An older snapshot can look familiar while omitting real changes that now exist.

Have a qualified infrastructure owner review the proposed reconciliation and the resulting plan. Keep manual state changes exceptional and controlled. Bypassing protections to remove an error message does not resolve the underlying identity or concurrency problem.

Best Practices

Separate adoption, address refactoring, provider upgrades, and functional infrastructure changes where feasible. Small, purposeful changes produce plans that are easier to review and recover from.

Keep version context and expected actions in the change record. Review drift and unknowns explicitly. A reviewer should be able to explain why each meaningful action appears and what evidence would invalidate the plan.

Exercise recovery in a controlled environment before relying on a runbook. Test access to backups, backend history, credentials, and review procedures without touching production state. Source-reviewed HCL, like this article's example, is preparation for that work rather than a recovery test.

Common Mistakes

Bad: Rename configuration and accept a create/delete plan as normal cleanup.

Correct: Determine whether the existing identity should be retained and use the appropriate address mapping, then review all remaining changes.

Bad: Restore old state and assume infrastructure was rolled back.

Correct: Reconcile current real objects with the proposed record. State recovery and infrastructure rollback are different operations.

Bad: Override a lock or state protection without diagnosing the owner.

Correct: Establish the concurrency and identity facts through the approved recovery process before considering exceptional action.

FAQ

Does import guarantee a no-change plan?

No. The destination configuration and provider interpretation can still differ from the existing object. Review the actual plan and the intended semantics.

Is a moved block a backup?

No. It records an address relationship. It does not preserve state history, user data, or a complete infrastructure recovery path.

When should the change stop?

Stop for an unexplained destructive action, uncertain ownership, wrong workspace, unresolved concurrent run, or unreviewable recovery artifact. Resolve those facts before proceeding.