Reference · Terraform

The Core Mental Model & Lifecycle

The one diagram everything else hangs off. Print it, pin it.

Terraform's whole job is to make three pictures of the world agree. Almost every command, surprise, and bug is explained by which two pictures it is comparing.

The three pictures

📝

Desired State

What you want. Your .tf files — the HCL config you write.

🗃️

State File

What Terraform thinks exists. terraform.tfstate — its memory / bookkeeping.

☁️

Real World

What actually exists. The live resources in AWS right now.

refresh State ↔ Real World. Terraform reads live infra and updates its memory. Catches drift (someone changed AWS by hand).

plan = diff Desired vs State. After refreshing, Terraform diffs your config against (refreshed) state to compute the change set.

Say it in one sentence: terraform plan = refresh state from the real world, then diff your desired config against it, and report the actions needed to make the real world match. terraform apply = do those actions, then record the result back into state.

The core workflow loop

Step	Command	What it actually does
Write	`edit *.tf`	You change the desired state.
Init	`terraform init`	Download providers, configure the backend (where state lives). Run once per new config / backend change.
Plan	`terraform plan`	Refresh → diff → show proposed actions. Changes nothing. Save with `-out=tfplan`.
Apply	`terraform apply`	Execute the plan in dependency order, then write results to state.
Destroy	`terraform destroy`	Plan + apply the removal of everything in state.

Source: Core workflow · plan reference

Reading a plan: the four symbols

Symbol	Action	Means
+	create	In config, not in state → make it.
~	update in place	In both, but an attribute differs → modify it.
-	destroy	In state, not in config → remove it.
-/+	replace	A changed attribute can't be updated live → destroy then recreate (look for "forces replacement").
0 to add	no-op	All three pictures already agree → nothing to do.

Mini glossary

Desired state: Your .tf configuration — the target you declare.
State (terraform.tfstate): Terraform's record mapping each config resource to a real-world object. Without it, Terraform can't tell "create new" from "I already made this."
Refresh: Re-reading real infrastructure to update state before diffing. Happens automatically inside plan/apply (skippable with -refresh=false).
Drift: When the real world no longer matches state — usually a manual change in the AWS console. Refresh surfaces it.
Plan: The computed set of create/update/destroy actions. A noun (the artifact) and a verb (the command).
Apply: Executing a plan, then writing the new reality back into state.
Resource: A thing Terraform manages (aws_s3_bucket). Tracked in state.
Data source: A read-only lookup of something Terraform doesn't manage. Refreshed, never created/destroyed.
Provider: The plugin that translates Terraform resources into API calls (e.g. the AWS provider).
Backend: Where the state file lives (local file, or remote like S3). Configured at init.