terraform-plan
Preview infrastructure changes before applying
TLDR
Generate and show the execution plan in the currently directory
Show a plan to destroy all remote objects that currently exist
Show a plan to update the Terraform state and output values
Specify values for input variables
Focus Terraform's attention on only a subset of resources
Output a plan as JSON
Write a plan to a specific file
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)