Skip to content

plan

Usage

The terraform plan command is used to create an execution plan, which allows you to preview the changes that Terraform intends to make to your infrastructure. By default, when Terraform creates a plan, it performs the following actions:

  • Reads the current state of any already-existing remote objects to ensure that the Terraform state is up-to-date.
  • Compares the current configuration to the prior state and notes any differences.
  • Proposes a set of change actions that should, if applied, make the remote objects match the configuration.

If the AWS provider is not configured with the correct credentials, Terraform will not be able to connect to AWS and verify the current state of your infrastructure. This will cause the terraform plan command to fail.

Planning Modes

Enabling any non-default planning mode in the terraform plan command will disable the default planning mode, and only one alternative mode can be used at a time.

-destroy (Destroy Mode)

The -destroy option in terraform plan generates a plan to destroy all remote objects, leaving an empty Terraform state. It is useful for temporary development environments where managed objects are no longer needed. To use this option, run terraform plan -destroy. Note that in Terraform v0.15 and earlier, this option is only supported by terraform plan, not terraform apply. To create and apply a plan in destroy mode in earlier versions, run terraform destroy.

Options:

  • out=FILE: saves the execution plan to a file

-refresh-only (Refresh Only Mode)

The -refresh-only option generates a plan that updates the state file with the current state of resources in the remote system. It does not make any changes to the infrastructure. This can be useful when updating the state file to reflect changes made outside of Terraform or before making changes.

Example:

terraform plan -refresh-only
  • Use out=FILE option to save execution plan to a file
  • Use destroy option to generate a plan to destroy all remote objects
  • Use refresh-only option to update the state file without making changes to the infrastructure

Planning Options

-refresh=false

The -refresh=false option prevents Terraform from refreshing the state file before generating an execution plan, which can save time. Use with caution and only when certain that the state file reflects the current state of the resources. Here's an example with code block:

terraform plan -refresh=false

If you make manual changes to resources and run terraform plan -refresh=false followed by terraform apply, Terraform will generate and apply a plan based on the current state file without refreshing it. This means that the plan will not consider any manual changes made to the resources outside of Terraform. As a result, when you apply the plan, Terraform may try to undo these manual changes and bring the resources back to the state described in the state file. This can cause unexpected behavior and data loss or other issues.

-replace=ADDRESS

The -replace=ADDRESS option in terraform plan generates a plan that forces the replacement of a specific resource. Use it to replace a resource instead of updating it in place or to force the recreation of a tainted resource.

Example:

terraform plan -replace=aws_instance.example

In this example, the aws_instance.example resource will be marked for replacement in the plan. Terraform will destroy the existing instance and create a new one in its place.

Use this option with caution as it can result in data loss or other issues. Review the plan before applying it to ensure it matches your expectations.

-target=ADDRESS

The -target option in terraform plan generates a plan that only includes changes to a specific resource. Use it to apply changes to a specific part of your infrastructure or troubleshoot issues with a specific resource.

Example:

terraform plan -target=aws_instance.example

terraform plan -target=module.module-1.aws_instance.ec2_module_1 -target=module.module-2.aws_instance.ec2_module_2

When resources are created using for_each or count, you can still target specific instances of these resources using the -target option with the terraform plan command.

For for_each resources

  • Target a specific instance by specifying its key in square brackets after the resource address

Example: terraform plan -target=aws_instance.example["key"]

For count resources

  • Target a specific instance by specifying its index in square brackets after the resource address

Example: terraform plan -target=aws_instance.example[0]

  • Target multiple instances of resources created with for_each or count by including multiple target options with different keys or indices

Example: terraform plan -target=aws_instance.example["key1"] -target=aws_instance.example["key2"]

Target all resources in loop

If you want to target all instances of a resource created using for_each or count, you can simply omit the square brackets and the key or index when specifying the resource address with the -target option. Here’s an example:

terraform plan -target=aws_instance.example

-var and -var-file

var

  • Used to set the value of a single variable in the root module of the Terraform configuration
  • Specify the key-value pair in the format of key=value
  • Use this option multiple times to set multiple variable values.

var-file

  • Used to set values for multiple variables by specifying a file containing variable definitions in the tfvars format
  • Can be used multiple times to include values from more than one file
  • Terraform loads values from the files specified first and then overrides them with any values specified using var options.

Example:

terraform plan -var="instance_type=t2.micro" -var="region=us-east-1"

terraform plan -var-file="variables.tfvars"

terraform plan -var-file="variables.tfvars" -var="region=us-east-1"

Use these options when you want to specify or override variable values when generating an execution plan. For more information about Terraform and its commands, check out HashiCorp’s official documentation.

General Options

-out=FILE

The -out=FILE option in the terraform plan command saves the execution plan to a file. This file can be passed to the terraform apply command to apply the changes in the plan. Here's an example:

# Generate and save the execution plan
terraform plan -out=myplan.tfplan

# Apply changes in the saved execution plan
terraform apply myplan.tfplan

-compact-warnings

The compact-warnings option displays warnings in a single-line format. It is useful when there are many warnings to review.

Example: terraform plan -compact-warnings.

-detailed-exitcode

  • The detailed-exitcode option changes the exit codes returned by terraform plan to provide more detailed information about the generated execution plan.
  • If the exit code is 0, it means that there are no changes to be made.
  • If the exit code is 1, it means that there was an error generating the plan.
  • If the exit code is 2, it means that there are changes to be made.

Here’s an example of how to use this option:

terraform plan -detailed-exitcode

This option can be useful when running Terraform in automation, as it allows you to determine whether there are changes to be made by checking the exit code of the terraform plan command. For example, you could use this option in a script to only apply changes if there are changes to be made.

-generate-config-out=PATH

If the configuration contains import blocks, Terraform can create HCL for any imported resources that are not yet present. The configuration is written to a new file at PATH, which must not already exist or an error will occur. Terraform may still attempt to write configuration if the plan fails for another reason.

-input=false

The -input=false option disables interactive input prompts for variable values when running terraform plan in automation. Terraform will generate an execution plan without prompting for variable values. If any required variable values are not provided through other means, Terraform will return an error. Here's an example:

terraform plan -input=false

-json

The -json flag with terraform plan generates a machine-readable JSON format of the execution plan for integration with other tools. Use terraform plan -json to generate the plan, and tools like jq to extract the needed information. Note that the flag only changes the output format and does not affect the behavior of the command.

Example:

terraform plan -json

-lock=false

lock=false flag in terraform plan disables state locking, allowing multiple Terraform processes to make changes to the same state without acquiring a lock. Use with caution as it can result in inconsistent state and unexpected behavior.

Example: terraform plan -lock=false

-lock-timeout=DURATION

The lock-timeout=DURATION flag sets a timeout for acquiring a state lock in terraform plan. This is important to prevent multiple processes from making conflicting changes to the same state. Use the lock-timeout flag to set the timeout duration in seconds, minutes, or hours.

Example: terraform plan -lock-timeout=30s.

It does not affect the behavior of the command in any other way. The flag can be used with other flags such as out or json.

-parallelism=n

terraform plan -parallelism=n controls the number of concurrent operations when generating an execution plan. Useful to limit concurrent operations to avoid API rate limits. Default value is 10. Example: terraform plan -parallelism=10.

-no-color

This option disables the use of terminal formatting in Terraform output. It's useful when the output needs to be rendered by a system that doesn't support terminal formatting.