Reading terraform plan Diffs Accurately (Associate Exam + Real-World Ops)

terraform plan visualizes the upcoming changes derived from state, real resources, and your current configuration. A common misconception: plan is purely a simulation — infrastructure does not change until you apply.

This article walks through how to read diff symbols correctly, when to use each major option, automatic checks in CI/CD, and drift detection tips — from both the Associate exam and real-world ops angles.

Plan Basics and How to Read Diff Symbols

terraform plan emits an execution plan derived from your HCL configuration, the current state, and a read of the real environment (refresh by default). The output shows what will change, in what order, and why — making it the core tool for review and risk reduction.

In the diff output, + means create, - means destroy, ~ means in-place update, and -/+ or +/- means replacement (destroy then recreate). ~ also appears at the attribute level, but -/+ at the resource header line means destroy and recreate is required.

• plan makes no real changes. Application happens via terraform apply.
• By default it refreshes (re-reads real resources). Control this with the -refresh flag.
• Output order follows dependencies. Destroy then create is preferred for safety.
• A saved plan file (-out) is only valid for the same workspace and configuration.

How plan fits in (config → plan → apply)

Minimum workflow and saving the output

terraform init
terraform plan -out=plan.tfplan
# Reviewers can inspect plan.tfplan with
# terraform show plan.tfplan

Key Options for Sharper Diffs

In operations you mix and match options for drift detection and scoped impact analysis. -refresh=false skips the external re-read, which helps in unstable network conditions for a tentative check — but raises risk because it does not reflect the latest real state.

-refresh-only creates a plan that only updates state to match the real resources, without touching anything in the cloud. You apply it with terraform apply -refresh-only — effectively a state sync (drift-to-zero) operation.

• -replace=<address> creates an explicit replacement plan (the modern replacement for taint).
• -destroy creates a destroy-only plan (useful for safely confirming final teardown).
• -var-file and -var pin the input values used in the plan, improving reproducibility.

How refresh-only works

Typical command combinations

# Strict drift check
terraform plan

# Tentative diff during network issues (avoid for final decisions)
terraform plan -refresh=false

# Plan that only updates state
terraform plan -refresh-only

# Replace a specific resource
terraform plan -replace=aws_instance.web

Automated Checks and Plan Sharing in CI/CD

In CI you use -detailed-exitcode to detect changes programmatically. 0 means no diff, 2 means changes detected, 1 means error. Posting plan output as a PR comment is a common pattern.

To improve reproducibility, generate a binary plan file with -out and convert it to machine-readable JSON with terraform show -json. Plan files depend on the Terraform version, backend, and workspace, so avoid carrying them across environments.

• Separating plan → review → approve → apply enforces least privilege.
• Applying a saved plan skips the approval prompt (well-suited to unattended apply).
• JSON output makes diff visualization dashboards possible.

Typical CI pipeline

Bash example: fail only when there are changes

set -euo pipefail
terraform init
if terraform plan -detailed-exitcode -out=plan.tfplan; then
  echo "No changes"
else
  code=$?
  if [ "$code" -eq 2 ]; then
    echo "Changes detected" >&2
    terraform show -json plan.tfplan > plan.json
    exit 2
  else
    echo "Plan failed" >&2
    exit $code
  fi
fi

Real-World Patterns and Pitfalls (Drift, Import, Unknown Values)

When existing resources have been changed manually, plan surfaces the drift as ~ or -/+. To take ownership of existing assets safely, bind them to state via terraform import first.

Data sources and values that are only resolved at apply time may appear as unknown in plan. Read carefully to check whether an unknown triggers a replacement requirement.

• Schedule regular plan runs for ongoing drift monitoring.
• Before importing, make sure the config matches the existing resource (name, tags, key attributes).
• If there are many unknowns, revisit your dependencies and lifecycle settings.

Drift detection flow

Importing and producing a minimal diff

# Bring an existing S3 bucket into state
# Match the HCL to the existing settings beforehand
terraform import aws_s3_bucket.logs my-existing-logs-bucket
terraform plan  # Confirm the drift is resolved

Topics Frequently Tested on the Associate Exam

plan is a proposal, and only apply actually performs changes. The meaning of -detailed-exitcode, and the fact that applying a saved plan from -out runs without approval, come up often.

Expect questions about intent: -target is not recommended for regular ops, -destroy builds a destroy plan, and -refresh-only builds a plan whose purpose is state sync.

• Exit codes: 0 = no changes, 2 = changes, 1 = failed.
• Applying a saved plan does not prompt (it can be unattended).
• Get plan JSON via terraform show -json (plan itself does not emit JSON directly).

Simplified exam decision chart

Summary of commonly tested commands

# Just check whether there are changes
terraform plan -detailed-exitcode

# Destroy plan
terraform plan -destroy

# Save then apply
terraform plan -out=plan.tfplan
terraform apply plan.tfplan

# Review as JSON
terraform show -json plan.tfplan > plan.json

Troubleshooting: Replacement, Move, Lock, and Permissions

When plan shows 'forces replacement', check whether an immutable attribute changed. If recreation is genuinely required by the spec, indicate intent explicitly with -replace for safety.

For resource renames or module reorganization, use a moved block to migrate state automatically without destroy/create. Backend lock contention and authorization errors are caught before plan runs — start by checking credentials and lock state.

• moved blocks enable safe renames — preferred over state mv.
• Wait for backend locks to release. Force-unlock is a last resort.
• Insufficient provider permissions tend to fail during the refresh phase of plan.

How a moved block works during rename

moved blocks and explicit replacement

# main.tf (Terraform 1.x)
moved {
  from = aws_instance.old_name
  to   = aws_instance.new_name
}

# Declare unavoidable recreation
# terraform plan -replace=aws_instance.web

Check with a Question

Frequently Asked Questions