Skip to main content
All right — Terraform state. You either love it or you hate it, but it’s absolutely essential for reliable Terraform workflows. This article explains what happens when your Terraform state file no longer matches the real-world infrastructure — a condition known as Terraform state drift — why it matters, and clear ways to resolve it. Why this matters (TL;DR)
  • Drift = differences between your Terraform configuration, the recorded Terraform state, and the actual cloud resources.
  • Left unresolved, drift can lead to unexpected resource changes, failed applies, or configuration confusion.
  • Terraform provides commands to detect drift and options to either enforce the configuration or adopt the real-world change.
How drift happens (simple flow)
  • You write Terraform configuration that declares resources (for example, several VMs with specific CPU and memory).
  • You run terraform apply. Terraform creates or updates resources and records their attributes in the state file (local or remote).
  • If someone or some process modifies resources directly in the cloud (manual edit, console change, autoscaling, or external automation), the real resources can diverge from the recorded state and your configuration. That divergence is state drift.
How Terraform detects drift When you run terraform plan, Terraform refreshes resource attributes (by default) to compare the real infrastructure against your configuration and state. If differences exist, terraform plan will show them as proposed changes.
  • Default behavior: terraform plan refreshes state and compares it to configuration.
  • Skip refresh: terraform plan -refresh=false avoids refreshing attributes (rarely recommended).
Commands quick reference
Common reconciliation choices You generally have two options when drift is detected:
  • Revert the change: Make the real infrastructure match your declared configuration.
  • Accept the change: Update Terraform state (and configuration) to adopt the real-world values.
Table: Reconciliation options at a glance Conceptual flows (step-by-step)
  • Revert flow
    1. terraform plan detects drift (plan shows changes that will be made to the real resources).
    2. terraform apply runs and updates the real infrastructure to match the configuration.
    3. Terraform updates state; now configuration, state, and reality are aligned.
  • Accept (adopt) flow
    1. terraform plan detects drift (plan shows differences).
    2. terraform apply -refresh-only updates the state file to reflect reality without changing resources.
    3. Update your Terraform configuration files (.tf) to match the real-world values.
    4. Run terraform plan/apply going forward to preserve consistency.
terraform plan refreshes resource attributes by default to detect drift. Use -refresh=false only when you intentionally want to skip that check (for example, in a controlled test where provider calls are undesirable).
Use terraform apply -refresh-only with care: it modifies the state to match the real world without changing any infrastructure. Only run it when you are certain the real-world changes should become the canonical state.
Best practices to avoid and manage drift
  • Make Terraform the single source of truth for infrastructure changes whenever possible.
  • Limit manual console edits; prefer automation or changes via Terraform.
  • Protect state with remote backends and state locking (e.g., S3 + DynamoDB lock, Terraform Cloud).
  • Use CI pipelines to apply changes so modifications are auditable and repeatable.
  • If manual changes are unavoidable, document and promptly reconcile by updating state and configuration.
Further reading and references Summary
  • State drift = mismatch between declared configuration, recorded Terraform state, and real-world resources.
  • terraform plan detects drift by refreshing resource attributes by default.
  • To revert drift: run terraform apply so the real resources match your configuration.
  • To accept drift: run terraform apply -refresh-only to update state, then update your configuration to reflect the real-world values.

Watch Video