Terraform Plan

With your configuration written in HCL and your working directory initialized (providers downloaded and workspace set up), the next step is to generate a plan. Terraform plan is your safety net: it previews the changes Terraform will make to match your configuration to real-world resources. That preview helps you catch unintended deletes or replacements before any real changes occur.

A purple infographic showing the Terraform workflow steps: Write Configuration (HCL), Initialize, Plan (highlighted with a red "You Are Here" marker), and Apply. Each step is represented by icons in rounded squares connected by arrows on a purple gradient background.

In this lesson you will learn:

What terraform plan does and why it’s important
How the plan lifecycle (refresh → diff → plan) works
How to read plan output, including symbols and summaries
How to save plans for review and guaranteed execution

What terraform plan does

Terraform generates an execution plan that describes all actions it will take to make real-world resources match your desired configuration.
Running terraform plan is a dry-run: it does not create, modify, or destroy resources.
The plan annotates resources with symbols that indicate the intended action:
- + create
- ~ update in-place
- - destroy
- -/+ destroy and then create replacement

Because Terraform shows the plan before you apply it, you can spot mistakes and avoid downtime, data loss, or other production impacts.

An instructional infographic titled "terraform plan" that explains what the Terraform plan command does (showing proposed resource changes and allowing a dry-run). It uses purple icons and includes a photo of a hand checking boxes on a checklist.

Why run plan first?

Best practice: always run terraform plan before terraform apply.
You can run terraform apply directly (it will implicitly plan first), but explicitly running terraform plan gives you a chance to review and validate the exact actions Terraform plans to perform.

How `terraform plan` works (refresh → diff → plan)

Terraform refreshes the state of existing resources by querying provider APIs to obtain the current real-world state.
Terraform compares the refreshed state with your desired configuration to compute the differences.
Terraform displays a legend, a detailed list of resource actions (create/update/destroy/replace), and a summary count.

Note the refresh step: Terraform needs an accurate baseline of what’s currently deployed before it can compute a correct plan.

Terraform plan refreshes the remote state by default (it queries provider APIs) so it knows the current resource state before calculating differences. You can disable this behavior with -refresh=false if needed, but the default refresh ensures the plan reflects the latest real-world state.

Plan output: symbols and what they mean

Symbol	Action	Explanation
`+`	Create	Resource will be created. Some attributes (like IDs) may be shown as `(known after apply)`.
`~`	Update in-place	Resource will be modified without replacement. Sensitive values are redacted as `(sensitive value)`.
`-/+`	Replace	Resource will be destroyed and recreated because a change forces replacement.
`-`	Destroy	Resource will be removed (often because it’s no longer in configuration).

Summary counts (for example, Plan: 2 to add, 1 to change, 2 to destroy) give a quick sense of the scope of change across your environment.

Example plan output

The example below shows a typical terraform plan terminal session. It includes refresh messages, the legend, detailed resource changes, and the final summary. Sensitive values are redacted.

$ terraform plan
vault_generic_secret.example_secret: Refreshing state... [id=secret/example]
random_pet.example: Refreshing state... [id=smashing-mutt]
vault_generic_secret.example_kv: Refreshing state... [id=secret/example1]

Terraform used the selected providers to generate the following execution plan.
Resource actions are indicated with the following symbols:

  + create
  ~ update in-place
  - destroy
  -/+ destroy and then create replacement

Terraform will perform the following actions:

  # random_pet.additional_pet will be created
  + resource "random_pet" "additional_pet" {
      + id        = (known after apply)
      + length    = 3
      + separator = "_"
    }

  # random_pet.example must be replaced
  -/+ resource "random_pet" "example" {
      ~ id     = "smashing-mutt" -> (known after apply)
      ~ length = 2 -> 3 # forces replacement
        # (1 unchanged attribute hidden)
    }

  # vault_generic_secret.example_kv will be updated in-place
  ~ resource "vault_generic_secret" "example_kv" {
      ~ data_json            = (sensitive value)
      id                     = "secret/example1"
      # (4 unchanged attributes hidden)
    }

  # vault_generic_secret.example_secret will be destroyed
  # (because vault_generic_secret.example_secret is not in configuration)
  - resource "vault_generic_secret" "example_secret" {
      - data                = (sensitive value) -> null
      - data_json           = (sensitive value) -> null
      - delete_all_versions = false -> null
      - disable_read        = false -> null
      - id                  = "secret/example" -> null
      - path                = "secret/example" -> null
    }

Plan: 2 to add, 1 to change, 2 to destroy.

------------------------------------------------------------------------

Note: You didn't use the -out option to save this plan, so Terraform can't
guarantee to take exactly these actions if you run "terraform apply" now.

Key details to notice in the output

Creates (+) often include attributes that will be populated only after apply (e.g., id = (known after apply)).
Updates in-place (~) show modified attributes. Secrets and other sensitive attributes are redacted as (sensitive value).
Replacements (-/+) highlight the attribute(s) that force replacement (for example, changing an immutable field).
Destroys (-) occur when a resource exists in state but is removed from your configuration.
The summary line provides an at-a-glance count of adds/changes/destroys.

Save plans for review and guaranteed execution

Saving a plan is useful for approval workflows: a saved plan captures the exact actions Terraform will take. Applying that plan later will execute exactly those actions without recalculating. Commands:

Task	Command
Save plan to file	`terraform plan -out=myplan.tfplan`
Apply a saved plan	`terraform apply myplan.tfplan`

Notes:

The plan file is a Terraform-specific (mostly binary) representation of the execution plan — it’s not for human reading.
Applying a saved plan executes the exact reviewed actions without re-planning, which is ideal for audit and CI/CD workflows.
Ensure you create and apply the saved plan with the same Terraform version and compatible providers; otherwise the saved plan may not be usable.

Saved plans are tied to the Terraform version and provider versions used to create them. Applying a saved plan with a different Terraform or provider version can fail or behave unexpectedly. Always generate and apply saved plans with consistent tooling.

Best practices

Always run terraform plan before terraform apply to preview changes.
Use terraform plan -out=... in CI/CD or team workflows to generate a reviewable plan artifact.
Review summary counts and replacements carefully — replacements (-/+) often indicate potential data loss or downtime.
Use -refresh=false sparingly; relying on the default refresh keeps the plan accurate to the current real-world state.
Keep Terraform and provider versions consistent across machines and CI runners to avoid plan/apply incompatibilities.

Links and references

In summary: terraform plan is an essential, low-risk way to preview and validate changes. Use it to catch mistakes early, save plans for team reviews, and rely on the clear plan output to understand creates, updates, replacements, and destroys before applying changes.

Course Introduction

Preparing Your Environment

Terraform Foundations

The Core Terraform Workflow

Terraform CLI

Terraform File Structure and Organization

Terraform Configuration - Fundamentals

Understading and Managing Terraform State

Marking Code Reusable

Refactoring Terraform State

Terraform Modules

Managing Resource Behavior and Dependencies

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

What terraform plan does

Why run plan first?

How `terraform plan` works (refresh → diff → plan)

Plan output: symbols and what they mean

Example plan output

Key details to notice in the output

Save plans for review and guaranteed execution

Best practices

Links and references

Watch Video

​What terraform plan does

​Why run plan first?

​How terraform plan works (refresh → diff → plan)

​Plan output: symbols and what they mean

​Example plan output

​Key details to notice in the output

​Save plans for review and guaranteed execution

​Best practices

​Links and references

Watch Video

What terraform plan does

Why run plan first?

How `terraform plan` works (refresh → diff → plan)

Plan output: symbols and what they mean

Example plan output

Key details to notice in the output

Save plans for review and guaranteed execution

Best practices

Links and references