Skip to main content
All right — Terraform state. You either love it or you hate it, but it’s essential to reliable infrastructure as code. In this guide you’ll learn what happens when your Terraform state diverges from real-world infrastructure (known as Terraform state drift), how Terraform detects that divergence, and practical ways to reconcile or adopt changes. Why this matters
  • Drift breaks the guarantees provided by IaC: reproducibility, auditability, and safe automation.
  • Detecting drift early prevents unexpected infrastructure changes and outages.
  • Choosing the right remediation keeps your Terraform configuration, state, and real resources aligned.
Conceptual setup
  • You author Terraform configuration files that describe your desired infrastructure.
  • Running Terraform records known resources and their attributes in the state file.
  • Terraform then creates or updates real resources in the provider (for example, VMs).
After a successful apply, three things are expected to match:
  • Desired configuration = Terraform configuration files
  • State = Terraform state file
  • Real world = Provider-managed resources
Imagine a simple configuration that defines two web servers. One is intended to have two CPUs and moderate memory; the other, one CPU and a lot of memory. After you apply the configuration, the configuration, the state, and the real cloud resources all align. Drift scenario If someone or something modifies a resource outside Terraform (for example, a colleague in the cloud console, a maintenance script, or an automated pipeline), the real resource can change without Terraform updating either the state file or your configuration. That mismatch is state drift: state ≠ real world.
A person stands in front of a transparent board with blue diagrams depicting a Terraform setup process involving state management.
Example: user changes a VM directly Suppose someone edits a VM instance in the cloud console and swaps CPU and memory values on one of the web servers. After that manual change:
  • Real-world VM attributes no longer match Terraform’s state file.
  • The Terraform configuration files still express the original desired values.
  • Terraform’s state remains stale until a refresh occurs.
This is drift — and it’s what terraform plan is designed to detect. How Terraform detects drift
  • When you run terraform plan, Terraform first refreshes the state by querying the provider for current attributes of managed resources.
  • It compares the refreshed state against the configuration you’ve authored.
  • Any differences that require action will be shown in the plan output as proposed changes.
Example commands
Resolving drift — two approaches You have two main options when you detect drift: revert the external change, or adopt it.
  1. Revert the external change (make real resources match your configuration)
  • Keep the configuration as the source of truth.
  • Use Terraform to change the real resource back to your desired values.
Typical workflow:
After apply, Terraform calls the provider APIs to modify the real resource and then updates the state file so configuration, state, and reality match again.
  1. Accept the external change (make Terraform state and configuration reflect the new real-world state)
  • If the external change was intentional and should become the desired state, update Terraform’s recorded state and then your configuration.
  • Use terraform apply -refresh-only to refresh the state from the provider and write those values into the state file without changing infrastructure.
Workflow to adopt an external change:
terraform plan refreshes the state from the provider and compares it to your configuration. Use terraform apply -refresh-only to update state without making infrastructure changes when you want Terraform to adopt external updates.
Practical notes and recommendations
  • Reverting external changes with terraform apply ensures the configuration remains the single source of truth.
  • Accepting external changes with -refresh-only writes the provider state into Terraform’s state file; follow this with configuration updates so IaC stays authoritative.
  • Enforce change control: restrict direct console edits via IAM, require PRs, or centralize changes through a CI/CD pipeline that runs Terraform.
  • Consider state locking (backends like S3 + DynamoDB, or remote backends) to prevent concurrent modifications to state.
Quick reference — common commands
Avoid relying on -refresh-only as a permanent workaround. Prefer workflows where all changes go through Terraform so configuration, state, and real resources remain consistent and auditable.
Summary
  • Terraform state drift happens when real-world resources diverge from the state file and configuration.
  • terraform plan detects drift by refreshing state and comparing it to configuration.
  • To revert drift, run terraform apply to make real resources match the configuration.
  • To accept drift, run terraform apply -refresh-only, then update your configuration and apply.
Links and references

Watch Video