how/state

Plan as a three-way diff: HCL vs state vs cloud

What terraform plan actually compares. Why it refreshes, how three sources become one plan, and what -refresh=false hides.

The familiar picture of git diff is a two-way diff: before and after. In Terraform there are three diffs, and they form a triangle:

main.tf is the desired state. What you wrote by hand.
terraform.tfstate is Terraform's cache. A snapshot of reality as Terraform last saw it.
the cloud (AWS, GCP, LocalStack) is the real state of the resources.

terraform plan first fixes one side of the triangle (state vs cloud, through refresh), then computes the diff along another (HCL vs state). Press ▶ to see how it comes together.

step 1/6·00 · after the previous apply

§ steps

The baseline position of the triangle: all three sources agree.
- HCL describes one bucket with the tag Owner = "student".
- state knows about this bucket and remembers the same tag.
- in AWS one such bucket actually exists.
Running plan again now returns No changes. This is the invariant Terraform always aims for after a successful apply.

recap

The main points about the three-way diff:

plan is refresh + diff, in that order. First state syncs with the cloud, then it compares against HCL. Reverse the order and you get a mess, not a plan.
A single plan can hold different kinds of mismatch: drift you need to roll back, and a new resource you need to create. They arrive in one output.
-refresh=false skips the first step. The plan becomes fast but blind: Terraform will not notice if someone edited the cloud by hand. Handy for local pre-commit checks, dangerous for CI and for a prod plan.
Terraform 1.5+ has a separate command terraform plan -refresh-only. It only gets the updated state, without comparing against HCL. Useful for drift detection.

Next: tf-drift on what to do once drift is already visible, and tf-state-mv-rm-import on imperative operations on state.

§ dig into the knowledge base

§ try it hands-on