Drift Detection
Configuration drift occurs when the real-world state of infrastructure no longer matches what Terraform's state file records — typically because someone (or some automated process) changed a resource directly through the cloud console, CLI, or another tool, bypassing Terraform entirely. Left unnoticed, drift causes surprising plan output, failed applies, or worse, an apply that silently reverts a manual emergency fix a human made outside Terraform. Drift detection is the practice of proactively identifying these divergences before they cause an incident.
Cricket analogy: If a curator waters and mows the pitch overnight without telling the groundstaff's logbook, the pitch report on file no longer matches reality, and the captain's plan for the toss can badly misfire.
How Terraform surfaces drift
Every terraform plan begins with a refresh step: Terraform queries the provider for the current real-world state of each managed resource and compares it against the last-known state file. Any difference appears in the plan as a proposed change back toward the configuration, even though nothing in the .tf files changed — this is the clearest sign of drift. Running terraform plan -refresh-only isolates exactly this: it shows only what has drifted, without proposing configuration-driven changes, and terraform apply -refresh-only updates the state file to match reality without touching real infrastructure.
Cricket analogy: Before every match, the third umpire cross-checks the stump-mounted camera feed against the official scorecard; any mismatch, like a bail that fell unrecorded, is flagged before it affects a decision.
$ terraform plan -refresh-only
aws_security_group.web: Refreshing state... [id=sg-0abc123]
Note: Objects have changed outside of Terraform
# aws_security_group.web has changed
~ resource "aws_security_group" "web" {
id = "sg-0abc123"
~ ingress = [
+ {
cidr_blocks = ["203.0.113.0/24"]
from_port = 22
to_port = 22
protocol = "tcp"
},
]
}
This is a refresh-only plan, so Terraform will not take any actions.Reconciling drift
Once drift is identified, teams have two choices: accept the manual change by codifying it into the .tf configuration and running terraform apply -refresh-only to sync state, or reject it by running a normal terraform apply, which reverts the resource back to the declared configuration. Neither choice is automatically correct — an emergency SSH-access rule added during an incident might need to be codified, while an accidental console edit should usually be reverted. Automated drift detection (Terraform Cloud's scheduled runs, or scheduled CI jobs running plan -refresh-only) catches this early instead of at the next unrelated deploy.
Cricket analogy: When a physio applies emergency strapping mid-innings that wasn't in the pre-match medical plan, the team doctor must decide whether to formally add it to the player's treatment record or remove it post-match.
Drift detection is essentially a continuous diff between 'what we declared' and 'what actually exists' — the earlier you run that diff after a manual change, the smaller and safer the reconciliation, which is why scheduled, automated drift checks outperform relying on the next ad hoc apply to surface it.
A plain terraform apply after drift has occurred will silently revert any manual changes back to the declared configuration — including emergency fixes made during an incident — so always run -refresh-only first to see what changed before deciding whether to accept or discard it.
- Drift is any divergence between real infrastructure and Terraform's recorded state, usually from out-of-band manual changes.
terraform plan -refresh-onlyisolates and reports drift without proposing configuration-driven changes.terraform apply -refresh-onlyupdates the state file to match reality without modifying real infrastructure.- A normal
terraform applyafter drift will revert manual changes back to the declared configuration — sometimes undesirably. - Reconciling drift means deciding whether to codify the manual change into .tf files or let Terraform revert it.
- Scheduled automated drift checks (Terraform Cloud, CI cron jobs) catch divergence early instead of at the next unrelated deploy.
Practice what you learned
1. What is configuration drift in the context of Terraform?
2. What does `terraform plan -refresh-only` do?
3. What is the risk of running a normal `terraform apply` immediately after undetected drift has occurred?
4. What does `terraform apply -refresh-only` do to real infrastructure?
5. Which practice best helps catch drift early, before an unrelated deploy accidentally reverts it?
Was this page helpful?
You May Also Like
The Terraform State File
Terraform's state file is the source of truth mapping your configuration to real-world resources. Understanding its structure and risks is essential for safe, collaborative infrastructure management.
terraform init, plan, and apply
The three-command core workflow of Terraform: init downloads dependencies, plan previews changes, and apply executes them -- forming a safe, repeatable provisioning cycle.
Importing Existing Infrastructure
Importing lets Terraform take ownership of resources that already exist in a cloud account, bringing them under state management without recreating them.
State Locking
State locking prevents two Terraform operations from writing to the same state file simultaneously, protecting against corruption and lost updates.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAnsible Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics