Terraform Guide

Terraform drift and diagrams: what a picture of your code can and cannot detect

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Two different problems share the word drift, and conflating them wastes money on the wrong tool. One is the gap between your cloud and your code, caused by console edits, competing automation, and pipelines that quietly stopped running. The other is the gap between your code and the documentation describing it. They need different detectors, and a diagram generated from source can only ever address the second.

Try it free
6 min readFor platform teams deciding which drift they are actually trying to solve

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

101/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Cloud drift: code against reality

Cloud drift is real infrastructure no longer matching the configuration that created it. Somebody resized an instance during an incident, an autoscaler changed a setting, a second automation touched the same resource, or a resource was created by hand and nothing manages it at all.

Detecting it requires comparing against the cloud, which means state and provider calls. The cheapest detector is terraform plan with -detailed-exitcode on a schedule: it returns 0 for an empty diff, 1 for an error, and 2 when the plan contains changes, so a scheduled job that alerts on 2 costs nothing to build. HCP Terraform packages the same idea as health assessments on its Standard and Premium editions, which compare real infrastructure against the configuration on a schedule. Scanners in the driftctl family go further and look for resources in the account that no configuration manages, which plan by design cannot see, though driftctl itself now describes its project as being in maintenance mode.

No parser can do any of this. Reading .tf files tells you what apply would make true, not what is currently true, and any tool claiming to detect infrastructure drift from source alone is describing something else.

Documentation drift: docs against code

The second drift is the one that quietly costs more, because it degrades every decision made from the diagram. The architecture changed in March, the picture in the wiki did not, and nobody can tell by looking. Unlike cloud drift, this one is fully detectable from source, because both sides of the comparison are files.

Datadef makes the comparison structural rather than textual. Each sync hashes the parsed draw plan, meaning the curated set of nodes, zones, counts, and edges that actually feed the diagram, into a short structure fingerprint. There are two skip points: a head commit that has not moved is never fetched at all, and a commit that moved without changing the fingerprint is fetched and parsed but stops before generation. A commit that adds a module, rewires two of them, or introduces a database changes the fingerprint and redraws.

The useful side effect is a clean signal. The regeneration history of a synced project is a log of when the architecture actually changed, filtered free of the formatting commits and dependency bumps that make git history useless for that question.

commit                          sha    fingerprint   sync
fix typo in variable docs       moved  unchanged     skipped
bump provider patch version     moved  unchanged     skipped
add module "redis"              moved  changed       regenerated
move subnet to another VNet     moved  changed       regenerated

The blind spot both detectors share

Neither the source nor the state knows about resources nobody manages. The DNS zone created before the repository existed, the subscription policy owned by another team, the bucket somebody imported and never finished importing: invisible to plan, invisible to a parser, and present in every incident.

The only fix is prose. Keep a dated list in the README naming what the repository deliberately does not own, with an owner per line. It is the highest-value page in an infrastructure repo precisely because no generator can produce it. Everything around it, the module reference table, the stack list, the environment differences, the architecture doc, is derivable and should be generated instead.

Run both, and know which is which

Keep plan-based drift detection for the cloud, and generate the architecture from source so the picture cannot rot. See what Terraform state does not tell you and how to detect stale diagrams.

FAQ

Does Datadef detect infrastructure drift?

No. It parses the .tf and .tfvars files of a repository and never reads state or calls a cloud provider, so it cannot know whether the running infrastructure still matches the code. Detecting that requires a plan against real credentials, or a scanner with read access to the account.

What is the difference between infrastructure drift and documentation drift?

Infrastructure drift is the cloud no longer matching the code, caused by manual changes or competing automation. Documentation drift is the docs and diagrams no longer matching the code. The first needs a plan or a cloud scan, the second needs generation from source.

How does a synced diagram know the architecture changed?

By hashing the parsed draw plan into a structure fingerprint. A commit that changes only comments, docs, or tests leaves that hash unchanged and the sync is skipped. A commit that adds or rewires modules and resources changes it, and the diagram regenerates.

Can a diagram show resources that exist in the cloud but not in the code?

No. A source-parsed diagram shows what the configuration declares. Unmanaged resources are invisible to it, and also invisible to terraform plan, which is why they should be written down as prose in the repository README with an owner and a date.

What is the cheapest way to detect cloud drift?

terraform plan with -detailed-exitcode on a schedule. The documented codes are 0 for an empty diff, 1 for an error, and 2 for a plan containing changes, so alerting on 2 is a drift signal you can route to a chat channel without buying anything. It will not find resources that no configuration manages, since plan only reconciles what Terraform already tracks.