Terraform Professional: Planning and Applying Infrastructure Changes

terraform plan compares your configuration with the current state and the real remote objects, then proposes the set of create, update, replace, delete and read actions that would make infrastructure match the configuration. It changes nothing: by default it refreshes its view of remote objects in memory, prints the proposal and exits.

A plan is shaped by planning modes and options on one side and run options on the other, and keeping the two groups apart explains most of how saved plans behave later:

-refresh=false skips re-reading remote objects and plans from state alone. It is faster but can miss drift, and it is still a normal plan: it never proposes deletions for resources the configuration still declares. Refresh-only plans, -replace and drift handling are covered in the state and drift lesson of this course.

-out=FILE saves the proposal for a later terraform apply FILE. Without -out, the plan is a preview only. terraform show FILE renders a saved plan for people, and terraform show -json FILE renders it for tools.

Each resource in a plan is prefixed with a symbol that says what will happen to it, and arguments inside it carry their own markers:

A # forces replacement comment marks the argument whose change cannot be made in place (for example an image ID or an availability zone). The header line says must be replaced. Which replacement order you get depends on the resource's lifecycle settings:

• create_before_destroy = true turns the default -/+ into +/-, so the new object exists before the old one is removed (useful for any object that clients or other resources must never lose, even briefly).
• replace_triggered_by adds reasons to replace but does not change the order.
• prevent_destroy = true makes any plan that would destroy the object fail with an error.
• ignore_changes on the argument removes the change from the plan, so no replacement is proposed.

When is a data source read during apply instead of during plan?

Terraform normally reads data sources while planning, so they do not appear as actions. A data source shows as <= with values (known after apply) when its read is deferred to apply, currently for one of two reasons, which terraform show -json records as the change's action_reason:

The two rows turn on different questions: the first on whether an argument value is unknown, the second on whether anything the data source depends on is still waiting to change. A pending dependency triggers the second reason even when every value the data source uses is already known. Anything computed from a deferred read is itself unknown until apply.

Running terraform plan -out=FILE and later terraform apply FILE applies exactly the operations recorded in the file, with no re-planning. That is the only way to guarantee that the apply step changes what the approver reviewed, even if new commits land between the two steps. terraform apply without a file argument always builds a fresh plan from whatever configuration is checked out.

What a saved plan carries and refuses:

• No approval prompt. Passing the file is the approval, so apply does not ask for yes. -auto-approve adds nothing in this mode.
• Recorded variable values. Input variables, sensitive ones included, are resolved at plan time and stored in the file, except variables declared ephemeral, which are never written to the plan. Apply does not ask for them again and does not re-read TF_VAR_* environment variables or .tfvars files.
• No planning modes or options. -var, -var-file, -target, -replace, -refresh=false and -destroy are rejected. To change a value or the scope, create a new plan and send that through review.
• Run options are accepted. -parallelism, -lock-timeout, -input=false and output options change how the plan is executed, not what it contains. For example terraform apply -parallelism=5 change-1234.tfplan reduces concurrency for an apply that is hitting API rate limits without touching the reviewed changes.

Why does Terraform reject a stale saved plan?

A plan is computed against a specific state. If any other operation writes that state after the plan was created (another pipeline's apply, a manual import or state move, a partially failed apply of this very plan), Terraform refuses to apply the file with a "Saved plan is stale" error rather than apply changes calculated from outdated data.

Locking does not help here: -lock-timeout lets a second apply wait for the lock, but once it gets the lock the plan is still stale. Terraform never merges or re-plans a saved plan. Nothing done to the old file revives it either: terraform refresh writes state again, and rolling state back to an older version makes it disagree with real infrastructure. The only fix is a new plan against the current state and a new review.

Apply the plan with the same working directory it was created in. HashiCorp's guidance for running Terraform in automation is to archive the entire working directory after planning, including the .terraform subdirectory that terraform init created (installed providers, modules, backend settings) and the dependency lock file, and restore it in the apply job.

The handoff fails, or is unsafe, when:

• Versions differ. Terraform errors if Terraform itself or any provider plugin was upgraded between plan and apply. Pin the Terraform binary to the same version in both jobs, and never run terraform init -upgrade in the apply job.
• The directory is not initialised. Uploading only the plan file to a fresh runner leaves it without providers or backend configuration.
• The platform differs. The plan can contain absolute paths and assumes the same operating system and CPU architecture. Restore the archived working directory at the identical absolute path on a runner with the same OS and architecture.

Settings such as TF_IN_AUTOMATION or extra flags at apply time do not make a moved plan acceptable. The JSON rendering of a plan cannot replace the binary file either: it is for inspection and policy checks, and terraform apply cannot execute it.

Why must plan files be treated as secrets?

Plan files store the real values needed to apply, including values from variables and attributes marked sensitive = true, in cleartext. The (sensitive value) placeholder is a feature of the human-readable display only; Terraform neither encrypts nor hashes those values in the file. The same holds for terraform show -json output, which keeps the value in after and only flags it in after_sensitive.

So restrict who can download plan artifacts, keep them only as long as the apply needs them, and never attach the JSON plan to a pull request or ticket where it would publish secrets.

Scripts should branch on the plan's exit code, and policy gates should parse terraform show -json, never the human-readable text.

What do the -detailed-exitcode codes mean?

Two consequences matter in practice. Under set -e, exit code 2 is non-zero, so a successful plan with changes aborts the script unless the code is captured (for example terraform plan -detailed-exitcode -out=tfplan || rc=$?) and only 1 treated as failure. And a drift job that treats every non-zero exit as "changes pending" turns errors, such as a syntax error or an unreachable backend, into false drift alerts; branch explicitly on 0, 2 and everything else. Warnings never change the exit code, and -detailed-exitcode works together with -out.

Which JSON fields should a policy gate check?

Each entry in resource_changes[] has a change object:

• actions: the list from the symbol table above. Replacement is encoded as ["delete","create"] or ["create","delete"] precisely so that a single "contains delete" test catches pure deletes and both replacement orders. An exact match on ["delete"] misses replacements.
• before / after: the prior and planned values. before is null for a create.
• after_unknown: same shape as after, with true for values known only after apply. Those values are omitted from after, so a gate that tests a planned attribute in after must first look up the same path in after_unknown and decide its policy for unknowns.
• before_sensitive / after_sensitive: same shape, true where a known value is sensitive. Combine them with after to avoid displaying secrets.

The optional action_reason (for example replace_because_cannot_update, delete_because_no_module, the deferred-read reasons) explains a change, but HashiCorp documents these codes as hints for display whose set may change, so do not base policy on them. resource_drift lists changes detected outside Terraform, not the changes this plan proposes.

-target=ADDRESS limits planning to the matching resource instances and everything they depend on. It never includes dependents: resources that reference the target are left out.

• Targeting a database instance that references a subnet group and a parameter group can plan all three; an alarm and a DNS record that reference the database are excluded.
• Targeting a module (-target=module.storage) includes every resource in that module, changed or not, plus their dependencies. A module that consumes its outputs (module.analytics) is not planned, so its edits and any knock-on changes stay pending.

Terraform warns that a targeted plan may be incomplete. HashiCorp reserves -target for exceptional circumstances, such as pushing one fix during an incident or recovering from a mistake, because routine use leaves changes undetected. Targeting is per run: nothing is stored in state, later runs are not limited, and a targeted apply locks state like any other. After a targeted apply, run a full plan without -target to see and deal with everything that still differs.

-target is a planning option, so it cannot be added when applying a saved plan.

Destroy is a planning mode. terraform plan -destroy -out=decommission.tfplan proposes deleting every object the configuration manages and saves the proposal for review; terraform apply decommission.tfplan then executes it. terraform destroy is an alias for terraform apply -destroy, which plans and applies in one command; neither it nor terraform apply has an -out option.

To retire part of a stack, such as a module call the business no longer needs, remove its block from the configuration and run the normal plan, review and apply. The plan proposes deleting the module's objects (action reason delete_because_no_module, or delete_because_no_resource_config for a removed resource block), and because they are no longer declared, later plans stay clean.

The details of removed and moved blocks belong to the import and lifecycle lesson of this course.

An unattended run must never wait for a person, and two runs must never write the same state at once. The relevant settings each solve one problem:

Where -auto-approve belongs is a design decision, not a convenience. In a disposable sandbox that nobody reviews, -input=false -auto-approve on a plain apply is acceptable. In production, apply a reviewed saved plan, which needs no approval flag at all. Pipeline design beyond these flags is covered in the CI/CD lessons of this course.

An apply is not transactional. Terraform writes each completed operation to state as it goes and never rolls back on error, so after a failure:

• Completed changes stay, both in the cloud and in state. Restoring an older state version would orphan the real objects.
• Unstarted changes are simply absent. State holds real objects only; there is no "pending" status.
• An object created but not finished is tainted. If a create fails after the provider made the object (for example a cluster whose creation timed out), or a creation-time provisioner fails, Terraform records the object as tainted because it may be partly configured. The next plan proposes replacing it, even with no configuration change.
• The saved plan is now stale, because the apply changed the state. It cannot be re-applied.

Recovery is therefore: fix the root cause, create a new plan (which proposes only what is left, plus replacement of tainted objects), review it and apply it. Nothing needs importing, because the completed objects are already tracked.

What does Ctrl-C do during an apply?

The first interrupt asks for a graceful stop: Terraform starts no new operations, lets in-flight operations finish, writes their results to state and exits with an error. Nothing is rolled back. A second interrupt forces an immediate exit, which can leave objects created in the cloud but missing from state, so avoid it.

With a cloud block (or the remote backend) and remote execution, terraform plan and terraform apply start runs in HCP Terraform and stream their output to your terminal; the operation runs with the workspace's variables and credentials, not the laptop's. Only local execution mode plans on the machine you run from.

For a VCS-driven workspace, every pull request against the tracked branch gets a speculative plan whose result is linked in the pull request, re-running as the pull request updates. Merging queues the real run. That is the reviewed path for these workspaces, because remote saved plans and remote terraform apply from the CLI are available only in workspaces without a linked VCS repository. A CLI that is new enough does not change this.

Other workspace features do different jobs: auto-apply applies successful runs on the tracked branch without confirmation, run tasks call external services during a run, and run triggers queue runs after another workspace applies. None of them makes a run plan-only.