Terraform operations · 12 min read · Reviewed 2026-09-20

Terraform Drift Detection: Configuration vs Cloud Reality

Terraform drift occurs when real cloud infrastructure no longer matches the configuration and state Terraform expects. A console edit, emergency change, manual deletion, provider default, or another automation can create that gap. Drift is not automatically a failure, but it is a signal that ownership and change history need attention before the next apply.

Start with this example

# Refresh the provider view and inspect the proposed reconciliation
terraform plan -refresh-only

# A normal plan compares desired configuration with the refreshed view
terraform plan

Three records can disagree

Terraform works with desired configuration, state, and the provider’s current view of the cloud resource. Drift is easiest to understand as a disagreement between those records. Your .tf files may say one thing, state may contain an older observation, and the cloud may now have a different setting.

A normal Terraform plan refreshes managed resources before proposing actions in most workflows. It can therefore show that Terraform would change real infrastructure to make it match configuration. A refresh-only plan is useful when you want to inspect and record the provider’s current values without proposing configuration-driven changes.

Investigate before choosing a direction

Start with the resource address, attribute, timestamp, actor, and reason for the out-of-band change. For example, a security rule might have been opened during incident response, or a cloud service might have added a provider-managed setting. The safe response depends on whether the real change is now the approved design.

If the cloud change is correct, update configuration through the normal review process so the desired state documents it. If the change was temporary or unsafe, prepare a reviewed change that returns the cloud to the intended configuration. Do not rely on a future apply to decide that question by accident.

Drift reveals ownership problems

Some drift is expected in a learning environment, but repeated drift in production often means several people or tools can change the same resources without a clear boundary. Console changes, CI pipelines, scripts, and multiple Terraform states should not all compete to manage one object.

Use least-privilege cloud access, protected deployment paths, documented emergency procedures, and clear ownership. For shared resources, expose deliberate inputs or module outputs instead of giving every application configuration broad control.

Put it into practice

Open Drift Explorer and load a sample report. For one changed resource, write whether the intended source of truth should be the configuration or the cloud setting, and explain who should approve the decision.

  1. Identify the exact resource and changed attribute.
  2. Decide whether the cloud change was intentional and authorised.
  3. Choose whether configuration should match reality or reality should return to configuration.
  4. Review a plan before applying any reconciliation.

Frequently asked questions

Does terraform plan detect drift?

A normal plan refreshes managed resources in most workflows, then compares the current provider view with configuration and state. It can reveal drift and propose actions to reconcile it, which is why the plan must be reviewed before applying.

What is the difference between a normal plan and a refresh-only plan?

A normal plan can propose infrastructure changes to match configuration. A refresh-only plan is for inspecting and recording the provider’s current view in state without proposing configuration-driven resource changes.

Should I edit Terraform state to fix drift?

Usually no. First determine whether configuration or the real cloud setting is the approved source of truth. Update the right one through a reviewed workflow; direct state editing can hide a problem without resolving ownership or safety concerns.

Continue with Terraform Architect

  • Explore a drift report

    Use Drift Explorer to read configuration-versus-cloud differences before deciding how they should be reconciled.

  • Review Terraform plans safely

    Learn how to examine creates, updates, replacements, and deletes before a change reaches the cloud.

  • Understand Terraform state

    See why state is operational data and why clear ownership matters when infrastructure changes outside Terraform.