Terraform drift is not automatically a reason to overwrite production. This checklist shows how to detect out-of-band changes, classify whether they are intentional, and choose a safe remediation path using plans, refresh-only operations, imports, configuration changes, or carefully controlled state recovery.
Overview
Terraform drift occurs when the infrastructure recorded in Terraform state no longer matches the real resource in the cloud or another provider. A person may have changed a setting in a console, an emergency script may have modified a resource, a provider may expose a newly observed attribute, or another automation system may control part of the object. Terraform drift detection is the process of finding and explaining that difference before taking action.
A normal terraform plan is the first diagnostic. Terraform refreshes its view of remote objects during planning, compares that view with the configuration and state, and proposes changes when the three do not align. The resulting plan is a proposal, not an instruction to apply it. Review it before deciding whether the desired outcome is to update the configuration, restore the declared configuration, preserve the remote change, or repair state.
Separate these questions:
- What changed? Identify the resource, attribute, old value, observed value, and source of the change.
- Should the change exist? Check approvals, incident notes, ownership, and dependencies.
- Where should the desired value live? It may belong in Terraform configuration, another controller, or nowhere if the change should be reversed.
- What is the safest action? Choose a plan-only review, configuration change, refresh-only state update, import, manual remediation, or state recovery.
For shared infrastructure, use a remote backend with locking where supported, restrict who can apply changes, and keep the state protected. State is sensitive operational data and should not be edited casually or copied into unprotected locations.
Checklist by scenario
Scenario 1: You need to detect and review drift
- Confirm the workspace, account, subscription, region, and variable set. A plan against the wrong environment can look like drift.
- Run
terraform planfrom the intended commit and record the Terraform and provider versions. - Save a reviewed plan when your workflow requires an approval artifact:
terraform plan -out=tfplan. Treat the plan file as sensitive because it may contain configuration values. - Classify every proposed change as expected, intentional but undocumented, unexpected, or unclear.
- Check whether the difference is caused by a changed remote value, a changed module or variable, provider behavior, replacement requirements, or an attribute managed by another system.
Do not apply merely to make the plan disappear. A clean plan is useful only when it represents the intended ownership and configuration model.
Scenario 2: The production change was intentional
- Capture evidence before changing anything: resource address, remote identifier, plan output, timestamps, console or API audit details, operator, and related incident or change record.
- Decide whether Terraform should become the source of truth for the new value.
- If yes, update the relevant variable, resource argument, module input, or generated configuration. Run formatting, validation, tests, and a new plan.
- If another controller owns the attribute, model that ownership deliberately. In narrowly justified cases, an appropriate
lifecycle.ignore_changesrule can prevent Terraform from contesting a field. Document exactly which attribute is ignored and who owns it. - If the change is temporary, record an expiry or follow-up date rather than leaving an undocumented exception.
Use ignore_changes sparingly. It suppresses Terraform's response to selected differences; it does not make the systems agree or prove that the remote value is safe.
Scenario 3: The remote change should be reverted
- Confirm that the declared Terraform configuration is still correct and that reverting will not remove an emergency mitigation or break a dependent service.
- Review the plan for destructive actions, replacement, dependency changes, and sensitive resources.
- Obtain the same approval required for any other production change.
- Apply through the controlled workflow, preferably from the reviewed commit and approved plan. Avoid making a separate console change immediately before or after the apply.
- Verify the resulting resource and run a follow-up plan to check for remaining differences.
A drift plan can include more than the manually changed attribute. Provider refresh behavior, defaults, dependent resources, or configuration changes can expand the proposed action. Read the complete plan.
Scenario 4: A resource exists but Terraform does not manage it
This is an ownership and import problem rather than ordinary drift. First establish that the resource belongs in the Terraform-managed boundary. Confirm its provider, exact identifier, region or project, and intended module address. Use an import workflow appropriate to the Terraform version and repository conventions, then write or generate a matching resource configuration and run a plan.
An import that produces a large follow-up plan is not automatically wrong. It indicates that state, configuration, and the provider's observed attributes still need reconciliation. Review the plan before applying anything. Do not import a resource simply to silence a monitoring alert or because its name looks similar to the intended object.
Scenario 5: State is stale, wrong, or damaged
- Stop concurrent applies and preserve the backend's existing state and relevant run logs.
- Confirm the backend, workspace, lock status, and credentials. A wrong backend can resemble missing infrastructure.
- Use read-only inspection such as
terraform state pullorterraform state listaccording to your security controls. Protect any output that may contain sensitive data. - Consider a refresh-only plan:
terraform plan -refresh-only. This evaluates whether state can be updated to reflect remote observations without proposing configuration-driven infrastructure changes. - If approved, a refresh-only apply can update state, but it should follow the same review, backup, locking, and approval controls as other state changes.
State recovery is not a substitute for fixing configuration or remote infrastructure. For complex corruption, conflicting ownership, or uncertain resource identity, stop and involve the platform owner before using state manipulation commands.
What to double-check
Before remediation, complete a drift evidence worksheet:
| Field | Record |
|---|---|
| Environment | Workspace, account, project, region, and commit |
| Resource | Terraform address, provider ID, and resource type |
| Difference | Declared, state-observed, and remote values where available |
| Cause | Console action, emergency script, controller, provider behavior, or unknown |
| Owner | Team responsible for the resource and disputed attribute |
| Decision | Revert, codify, ignore with ownership, import, or repair state |
| Evidence | Plan file, audit record, ticket, approval, and verification result |
Also verify whether the proposed action is in place or replacement. Check dependencies, backup and recovery options, maintenance constraints, secrets handling, backend locking, and the permissions used by the plan and apply. A plan generated with different credentials, variables, or provider versions may not be comparable to the approved plan.
For scheduled drift scans, make the output actionable. Report the workspace, resource address, severity, owner, first-seen time, and whether the difference is blocking or informational. Route the result to the team that can resolve ownership, rather than treating every difference as an infrastructure incident.
Common mistakes
- Applying without reading the plan: Drift detection is a review step, not an approval shortcut.
- Using refresh-only to hide configuration drift: Refreshing state does not update the Terraform files that define the desired infrastructure.
- Running with the wrong environment: Verify backend, workspace, variables, credentials, account, and region before interpreting output.
- Adding broad ignore rules: Ignoring an entire resource can conceal meaningful changes and weaken ownership boundaries.
- Manually editing state: State commands can alter resource identity and relationships. Use them only with a documented recovery plan and backup.
- Importing without configuration: Import establishes state association; it does not automatically create a maintainable desired configuration.
- Ignoring replacement markers: An apparently small attribute change may require resource recreation. Confirm the effect and recovery path.
- Allowing untracked emergency changes to persist: Record the exception, assign an owner, and set a deadline to codify or revert it.
When to revisit
Revisit this workflow before seasonal planning or other periods when infrastructure capacity, ownership, or access patterns change. Repeat it after console changes, emergency remediation, provider or module upgrades, backend migrations, imports, and changes to CI/CD policy. Platform teams should also review scheduled drift scans when resource ownership changes or when a new controller begins managing an attribute.
At each review, test the complete path in a non-production environment: detect, classify, approve, apply or refresh-only, and verify. Confirm that backend locking works, state backups are available, plan artifacts are protected, and the CI policy requires an approved plan for the intended environment. Recheck command behavior and provider-specific details after major Terraform or provider releases rather than assuming older examples still apply.
Use this final action list: run a plan from the correct commit; save and inspect the evidence; identify the owner and cause; choose codify, revert, ignore, import, or state recovery; obtain approval; protect the lock and state; apply only the reviewed action; and run a verification plan afterward. That sequence keeps Terraform drift detection from becoming an automatic production overwrite and turns it into a repeatable platform engineering control.