Infrastructure drift is the gap between what Terraform or OpenTofu records in configuration and state, and what actually exists in a cloud environment. This practical workflow shows how to detect that gap, investigate whether a change was intentional, and reconcile it without blindly overwriting production resources.
Overview
Terraform and OpenTofu are designed to make infrastructure changes predictable: configuration describes the desired state, state records the objects under management, and a plan compares that information with the provider's current observations. Drift can appear when someone changes a resource in a cloud console, another automation system updates it, a provider reports a changed value differently, or a failed operation leaves configuration and reality out of alignment.
Drift detection is not the same as immediate remediation. A plan that proposes changes is evidence to investigate, not permission to apply. The safe sequence is:
- Confirm that you are using the correct working directory, workspace or state, credentials, and cloud account.
- Refresh observations and generate a plan without applying it.
- Classify each difference as intentional, accidental, provider-generated, or uncertain.
- Choose whether to update code, import a resource, preserve an external change, or revert the live resource.
- Review the resulting plan and apply only through the normal approval and state-locking process.
Keep the state backend protected and use a separate review path for production. Plan output can expose resource names, network details, identifiers, and sometimes sensitive values or their surrounding context. Store it according to your organization's access and retention rules. For related operational controls, see the cloud data fabric implementation checklist.
Checklist by scenario
Scenario 1: A routine audit finds unexpected changes
- Establish identity and scope. Record the repository commit, tool version, provider configuration, workspace or state address, account or subscription, and region. Many apparent drift incidents are caused by inspecting the wrong environment.
- Initialize without changing infrastructure. Use the repository's standard initialization process and verify that the backend and provider selections are expected. Do not create a new local state file by accident when the real state is remote.
- Generate a normal plan. Run the team's usual planning command, such as
terraform planortofu plan, with the appropriate variable and locking options. Review the proposed actions before considering any apply. - Separate refresh changes from configuration changes. The plan may show that state must be updated to reflect the remote object before it evaluates configuration. Inspect which attributes changed and whether the proposed action is an update, replacement, creation, or destruction.
- Capture evidence. Compare the plan with cloud audit records, deployment logs, pull requests, provider changes, and recent incident activity. Note who or what made the live change and when.
If the change was intentional, update the configuration and review the resulting plan. If it was accidental, decide whether the safest correction is an approved apply or a targeted change made through the cloud provider followed by a fresh plan. Avoid editing state manually unless you have a documented recovery procedure and understand the consequences.
Scenario 2: You want to inspect drift without proposing configuration changes
A refresh-only plan is useful when the immediate question is, “What does the provider currently report compared with state?” The exact command and supported behavior can vary by Terraform or OpenTofu version, so confirm it against the tool version used by the repository. A commonly used form is:
terraform plan -refresh-onlyor:
tofu plan -refresh-onlyThis mode is for reviewing state observations and deciding whether state should be updated. It is not a substitute for a normal plan: a refresh-only result does not tell you whether the declared configuration will converge with the newly observed values. After reviewing it, run a regular plan before approving remediation.
Scenario 3: A resource exists but is not managed correctly
If a resource was created outside Terraform or OpenTofu and should now be managed, import it rather than recreating it. First add an appropriate resource block, then use the tool's import workflow with the correct resource address and provider-specific identifier. After import, run a plan and align the configuration with the resource's actual settings.
Import is appropriate when ownership is moving into infrastructure as code. It is not a way to hide an unexplained difference. Confirm the resource identity, dependencies, lifecycle settings, and sensitive arguments before importing. Some resources require multiple related objects or additional configuration to produce a stable plan.
Scenario 4: A live system intentionally owns an attribute
Sometimes another controller, autoscaler, certificate system, or platform process is expected to modify a particular attribute. In that case, consider whether the resource should be modeled differently or whether a lifecycle rule such as ignore_changes is justified. Use it narrowly for documented attributes, not as a blanket way to silence drift.
Before ignoring a change, answer three questions: who owns the attribute, how is its validity monitored, and what happens if the external controller stops working? Document the ownership boundary in code or adjacent operational documentation. Ignoring a field can prevent Terraform or OpenTofu from correcting it, so it should be an explicit design decision.
What to double-check
- State and locking: Confirm that only one authorized operation is changing the state. Use the backend's locking mechanism where available, and do not bypass a lock merely to make a command proceed.
- Replacement risk: Pay special attention to plans containing “destroy and create,” replacement markers, subnet, security group, database, identity, or storage changes. A small attribute difference can have a large operational effect.
- Unknown values: Provider-computed values may be unknown during planning or may change after an apply. Distinguish normal computed behavior from a meaningful configuration mismatch.
- Defaults and normalization: Cloud APIs and providers may normalize names, ordering, omitted defaults, tags, or policy representations. Check whether the difference is persistent and actionable before changing code.
- Provider and module changes: A provider upgrade, module refactor, or changed variable default can make a previously stable plan appear different. Reproduce the plan from the intended commit and dependency lock file.
- Secrets and plan artifacts: Treat plan files, logs, and CI annotations as potentially sensitive. Avoid posting full plans in public tickets or chat. Review your secrets workflow alongside infrastructure workflows using the secrets management comparison.
- Policy and approval gates: Ensure destructive actions, production changes, and changes to identity or network boundaries receive the required human review. A clean plan is not proof that the proposed design is safe.
For recurring detection, run plans from a controlled CI environment against the intended state and credentials. A scheduled plan can alert on changes, but the alert should link to a protected artifact and a runbook rather than automatically applying every difference. Include exit-code handling appropriate to the tool and CI system, and test the workflow with both no-change and change cases.
Common mistakes
- Applying immediately after seeing drift: A plan can contain unrelated changes, replacements, or a wrong-environment result. Investigate first.
- Using refresh-only as the final plan: Refresh-only inspection helps update observations; it does not replace a normal convergence plan.
- Running with the wrong variables: A different variable file, workspace, region, or account can produce a convincing but irrelevant result.
- Deleting and recreating to “fix” ownership: Import or adopt existing resources when appropriate. Destruction can cause avoidable downtime or data loss.
- Adding broad ignore rules: Ignoring entire resource blocks makes drift invisible. Prefer a narrow, documented ownership boundary.
- Editing state as a first response: State surgery can conceal the underlying problem and create a mismatch between state, code, and the live resource. Reserve it for controlled recovery.
- Comparing only the final summary: Read the attribute-level changes and dependency context. The reason for a replacement is often visible only in the detailed plan.
When to revisit
Revisit this workflow before seasonal planning or capacity cycles, after provider, Terraform, OpenTofu, module, or cloud-platform changes, and after incidents involving failed applies or manual recovery. It is also worth reviewing after a new autoscaler, controller, security platform, or deployment system begins modifying resources that were previously managed only by infrastructure as code.
At least twice a year, test the complete drift process in a non-production environment. Confirm that scheduled plans use the intended backend, that alerts are actionable, that plan artifacts are protected, and that reviewers can distinguish an intentional change from an unauthorized one. Update command examples and CI checks when the repository's tool versions or workflow conventions change.
Before reconciling any real drift, use this short final checklist:
- Identify the exact state, environment, credentials, and code revision.
- Run a refresh-aware inspection and a normal plan.
- Classify every proposed change and record its owner.
- Choose code update, import, narrow ignore, or live-resource correction deliberately.
- Check for replacement, destruction, sensitive output, and dependency effects.
- Obtain the required review, preserve the plan context, and apply with state locking.
- Run a post-apply plan and document any remaining intentional differences.
Used consistently, this process turns Terraform and OpenTofu drift detection into a routine reconciliation practice rather than an emergency response to an unexpected plan.