Module 3: Core Terraform Workflow

Lesson 3.4: Generating and Reviewing a Plan

Plain language

terraform plan shows what Terraform would do, without doing it. Treat it as the change request that reviewers approve.

Under the hood

For a normal plan, Terraform:

  1. Reads the configuration and current state, and takes a state lock if the backend supports locking.
  2. Refreshes by reading every managed object from its API to find the actual current values.
  3. Diffs the desired state against the refreshed state.
  4. Prints a proposed set of actions. Neither state nor infrastructure is changed. The refreshed values aren't saved unless you apply.

Reading a plan

Text
  # docker_container.web must be replaced
-/+ resource "docker_container" "web" {
      ~ id    = "3f1c..." -> (known after apply)
      ~ name  = "tf-course-web-dev" -> "tf-course-web-prod" # forces replacement
        # (12 unchanged attributes hidden)
    }

Plan: 1 to add, 0 to change, 1 to destroy.
Symbol Meaning
+ Create
- Destroy
~ Update in place
-/+ Replace: destroy, then create (the default)
+/- Replace: create, then destroy (create_before_destroy)
<= Read a data source during apply
(known after apply) Value is computed by the provider and isn't known yet
# forces replacement This argument change can't be applied in place

Plan flags

Flag What it does
-out=tfplan Saves the plan to a binary file for an exact later apply
-refresh-only Proposes only updating state to match real infrastructure. Plans no infrastructure changes. Use it to review drift (Module 6).
-refresh=false Skips refresh and trusts state as-is. Faster but riskier.
-target=ADDRESS Limits planning to one resource and its dependencies. Prints a warning. Use it only for exceptional recovery.
-replace=ADDRESS Forces replacement of a resource even if nothing changed. This replaces the deprecated terraform taint.
-destroy Plans the destruction of all managed resources
-var 'k=v' / -var-file=FILE Supplies variable values (precedence is covered in Module 4)
-detailed-exitcode Exit 0 = no changes, 1 = error, 2 = changes present. Useful in CI.
-input=false, -lock=false, -parallelism=N Automation and tuning options