terraform-plan

Generate and show the execution plan in the currently directory

$ terraform plan

$ terraform plan -destroy

$ terraform plan -refresh-only

$ terraform plan -var '[name1]=[value1]' -var '[name2]=[value2]'

$ terraform plan -target [resource_type.resource_name[instance index]]

$ terraform plan -json

$ terraform plan -no-color > [path/to/file]

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

-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.

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.

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.

`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).

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.

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.

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