LinuxCommandLibrary

terraform-plan

Preview infrastructure changes before applying

TLDR

Generate and show the execution plan in the currently directory

$ terraform plan
copy

Show a plan to destroy all remote objects that currently exist
$ terraform plan -destroy
copy

Show a plan to update the Terraform state and output values
$ terraform plan -refresh-only
copy

Specify values for input variables
$ terraform plan -var '[name1]=[value1]' -var '[name2]=[value2]'
copy

Focus Terraform's attention on only a subset of resources
$ terraform plan -target [resource_type.resource_name[instance index]]
copy

Output a plan as JSON
$ terraform plan -json
copy

Write a plan to a specific file
$ terraform plan -no-color > [path/to/file]
copy

SYNOPSIS

terraform plan [options] [DIRECTORY]
terraform plan [options] PLAN_FILE

PARAMETERS

-out=FILE
    Saves the generated plan to a specified file, allowing it to be used later with `terraform apply FILE`.

-destroy
    Creates a plan to destroy all managed remote objects, effectively tearing down the infrastructure.

-refresh=false
    Skips the state refresh before generating the plan, using only the existing state file.

-var 'key=value'
    Sets a variable for the plan, overriding variables defined elsewhere. Can be used multiple times.

-var-file=PATH
    Loads variables from a specified file (e.g., `terraform.tfvars`). Can be used multiple times.

-input=false
    Disables interactive prompts for input variables.

-lock=false
    Disables state locking for the duration of the plan. Use with caution.

-detailed-exitcode
    Returns a detailed exit code: 0=no changes, 1=error, 2=changes proposed. Useful for scripting.

-json
    Outputs the plan in machine-readable JSON format.

-target=RESOURCE_ADDRESS
    Directs Terraform to only plan changes to the specified resource or module. Use sparingly, primarily for recovery.

-replace=RESOURCE_ADDRESS
    Marks a specific resource instance to be replaced (destroyed and re-created). Use sparingly for specific scenarios.

-compact-warnings
    Shows warnings more compactly, only displaying the summary.

-refresh-only
    Only refreshes the state without planning any configuration changes or proposing new actions.

DESCRIPTION

The terraform plan command is a fundamental component of the Terraform workflow, providing a crucial "dry run" capability. It computes the differences between your Terraform configuration files, the current state of your infrastructure (as recorded in the Terraform state file), and the actual state of the remote infrastructure providers. The primary purpose of `terraform plan` is to show you exactly what actions Terraform will take if you were to proceed with a `terraform apply` command. This includes creating new resources, updating existing ones, or destroying resources that are no longer defined or have been marked for deletion. It allows for a thorough review of proposed changes, helping to prevent unintended modifications or costly errors before they are committed to your live environment. The output clearly outlines each planned operation, making it an indispensable tool for validation, collaboration, and ensuring infrastructure stability.

CAVEATS

A plan is a prediction: The actual `terraform apply` execution might differ if external factors change between `plan` and `apply` (e.g., manual modifications, race conditions on cloud resources).
Use `-target` and `-replace` options with extreme caution. They can lead to state drift and are generally intended for recovery or specific targeted operations rather than routine usage.
Sensitive data in your configuration, if not properly marked with `sensitive = true`, might be displayed in the plan output.

CI/CD INTEGRATION

`terraform plan` is critical in automated CI/CD pipelines. By running `plan` with `-detailed-exitcode`, pipelines can automatically determine if infrastructure changes are proposed (exit code 2) and require manual review or if no changes are necessary (exit code 0).

SECURITY REVIEW

The plan output serves as an audit trail and a valuable artifact for security and compliance reviews, ensuring that proposed infrastructure changes align with organizational policies.

HISTORY

The `terraform plan` command has been a core and indispensable part of the Terraform CLI since its early days. Introduced as a fundamental safety mechanism, it underpins Terraform's "infrastructure as code" paradigm by allowing users to preview and approve infrastructure changes before they are applied. Its evolution has focused on providing clearer output, more control over execution (e.g., `-target`, `-replace`), and integration with CI/CD systems through features like detailed exit codes and JSON output.

SEE ALSO

terraform apply(1), terraform init(1), terraform show(1), terraform refresh(1)

Copied to clipboard