Terraform Plan Review English: Describing Infrastructure Changes Clearly
Learn the English vocabulary and phrasing for Terraform plan reviews: reading the diff, flagging risky changes, and writing PR comments that prevent outages.
A terraform plan shows exactly what will change before you apply it. Reviewing that plan is one of the highest-leverage moments in infrastructure work — a misread ~ versus -/+ can mean a five-minute config update or a destroyed database. Communicating clearly about the plan, in writing and in review comments, is a real skill. Here’s the English you need.
Reading the plan symbols out loud
Terraform uses symbols you need to name correctly when discussing them:
| Symbol | Meaning | How to say it |
|---|---|---|
+ | create | ”This creates a new bucket.” |
- | destroy | ”This destroys the old security group.” |
~ | update in place | ”This updates the tag in place.” |
-/+ | destroy then recreate | ”This replaces the instance — destroy and recreate.” |
<= | read data source | ”This just reads existing data.” |
The critical distinction is in-place update (~, safe) versus replacement (-/+, dangerous). Replacement means the resource is destroyed and a new one created, which for stateful resources can mean data loss.
“Heads up — line 47 shows a
-/+, so this isn’t an in-place update; it’s a full replacement of the RDS instance. That would wipe the data unless we have a snapshot.”
Key vocabulary
| Term | Meaning |
|---|---|
| Drift | When real infrastructure differs from the state file |
| State | Terraform’s record of what exists |
| Apply | Executing the planned changes |
| Plan | Previewing changes (a dry run) |
| Force replacement | A change that requires destroy + recreate |
| Blast radius | How much is affected if this goes wrong |
| Idempotent | Running it again produces no new changes |
“There’s some drift here — someone changed the rule in the console, so the plan wants to revert it. Let’s confirm that’s intentional before we apply.”
Flagging risky changes in review
The whole point of plan review is catching dangerous changes. Lead with the risk, clearly but without panic.
| Vague | Clear |
|---|---|
| ”This looks bad." | "This forces a replacement of a production database — that’s a hard blocker for me." |
| "Maybe check this." | "Can you confirm the -/+ on the load balancer is expected? It’ll briefly drop traffic." |
| "Is this OK?" | "What’s the blast radius if this subnet change goes wrong?” |
Useful review phrases:
- “This is a hard blocker — it replaces a stateful resource.”
- “Non-blocking nit: the resource name doesn’t follow our convention.”
- “Can you double-check that this won’t recreate the VPC?”
- “I’d want a snapshot before we apply this.”
The contrast between hard blocker (must fix) and nit / non-blocking (minor) is essential review vocabulary.
Writing the PR description for an infra change
Infra PRs need extra care because the reviewer often can’t easily reproduce the plan. Paste the relevant plan output and summarise it.
What: Bumps the node pool from 3 to 5 instances and adds an autoscaler.
Plan summary:
2 to add, 1 to change, 0 to destroy. The change is an in-place tag update — no replacement. Nothing is destroyed.Risk: Low. Scaling up doesn’t disrupt running pods. The autoscaler is additive.
Apply window: Anytime; zero downtime expected.
Always state the headline counts — “X to add, Y to change, Z to destroy” — because the destroy count is what reviewers scan for first.
“The line everyone should look at: 0 to destroy. This is purely additive.”
Describing what a change does and doesn’t touch
Reviewers fear unintended side effects. Reassure them explicitly.
- “This change is scoped to the staging workspace only.”
- “It doesn’t touch networking or IAM.”
- “The only resource affected is the CloudWatch alarm — everything else is untouched.”
“I’ve deliberately kept the blast radius small: one module, one environment, no shared resources.”
Before and after: a full rewrite
Before (unclear, scary):
“i changed the terraform. plan says some things will be destroyed and recreated I think. should be fine maybe. apply when you want.”
After (precise, reassuring where appropriate, alarming where needed):
“The plan reads 1 to add, 0 to change, 1 to destroy. ⚠️ That destroy is the production NAT gateway, and the add is its replacement with a new EIP — so we’ll lose the static outbound IP. Anything allow-listing that IP downstream will break. This is a hard blocker until we coordinate the IP change with the partner team. The rest of the diff is in-place and safe.”
Notice how the rewrite separates the dangerous part from the safe part and names the concrete consequence (losing the static IP).
Common mistakes
- Confusing “change” and “replace.” A
~change is in place and safe; a-/+replacement destroys and recreates. Never call a replacement just “a change.” - Saying “delete” for
destroy. Terraform’s verb is destroy. “This destroys the bucket,” not “this deletes.” - Forgetting to mention destroy count. Reviewers always want the destroy count first. Lead with it.
- Translating “apply” as “implement.” In Terraform, apply is the specific command. Say “run
terraform apply,” not “implement the terraform.”
A reusable plan-review comment template
**Plan summary:** X to add, Y to change, Z to destroy.
**Replacements (`-/+`):** [list any, or "none"]
**Stateful resources affected:** [list, or "none"]
**Blast radius:** [one environment / shared / production]
**Verdict:** ✅ looks safe / ⚠️ needs a snapshot first / ⛔ hard blockerKey takeaways
- Name the symbols precisely:
~is in-place,-/+is replacement (dangerous). - Lead every summary with “X to add, Y to change, Z to destroy” — the destroy count first.
- Separate hard blockers from non-blocking nits in your comments.
- Reassure reviewers about scope: “doesn’t touch X,” “blast radius kept small.”
In infra reviews, clear English is a safety control. The clearer your plan summary, the less likely a tired reviewer approves something that destroys production.