How to use the command 'terraform plan' (with examples)

Terraform is an open-source infrastructure as code tool that allows you to create and manage your infrastructure across various cloud providers. The terraform plan command is used to generate and show Terraform execution plans. It is a crucial step in the infrastructure deployment process as it allows you to preview the changes that will be made to your infrastructure before applying them.

Use case 1: Generate and show the execution plan in the currently directory

Code:

terraform plan

Motivation: Running terraform plan without any additional arguments generates a preview of the changes that Terraform will make to the infrastructure. This is useful when you want to review the execution plan and verify that it will create, modify, or destroy the desired resources.

Explanation: The command terraform plan generates a detailed execution plan based on the Terraform configuration files in the current directory. It analyzes the changes between the current state and the desired state described in the configuration files and shows how it will create, modify, or destroy resources.

Example output:

Terraform will perform the following actions:

  # aws_instance.example will be created
  + resource "aws_instance" "example" {
      + ami           = "ami-0c94855ba95c71c99"
      + instance_type = "t2.micro"
      + subnet_id     = "subnet-1234567890"
    }

  # aws_s3_bucket.example will be created
  + resource "aws_s3_bucket" "example" {
      + bucket = "example-bucket"
      + region = "us-east-1"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

Use case 2: Show a plan to destroy all remote objects that currently exist

Code:

terraform plan -destroy

Motivation: In certain scenarios, you might want to destroy all the resources managed by Terraform. By using the -destroy flag with terraform plan, you can generate a plan specifically focused on destroying all remote objects that currently exist.

Explanation: The command terraform plan -destroy generates a detailed execution plan to destroy all remote objects managed by Terraform. It shows which resources will be destroyed and any additional resources that might be affected.

Example output:

Terraform will perform the following actions:

  # aws_instance.example will be destroyed
  - resource "aws_instance" "example" {
      - ami           = "ami-0c94855ba95c71c99"
      - instance_type = "t2.micro"
      - subnet_id     = "subnet-1234567890"
    }

  # aws_s3_bucket.example will be destroyed
  - resource "aws_s3_bucket" "example" {
      - bucket = "example-bucket"
      - region = "us-east-1"
    }

Plan: 0 to add, 0 to change, 2 to destroy.

Use case 3: Show a plan to update the Terraform state and output values

Code:

terraform plan -refresh-only

Motivation: When you need to update the Terraform state and output values without making any changes to your infrastructure, using the -refresh-only flag with terraform plan is useful. It allows you to inspect the differences between the current state and the desired state without modifying any resources.

Explanation: The command terraform plan -refresh-only generates a detailed execution plan to update the Terraform state and output values based on the current state and the configuration files. It prioritizes refreshing the state to ensure it accurately reflects the current state of the resources.

Example output:

Terraform will perform the following actions:

  # aws_instance.example (refresh) will be updated in-place
  ~ resource "aws_instance" "example" {
        id   = "i-0123456789abcdef0"
        tags = {
            "Name" = "example-instance"
        }
    }

Plan: 0 to add, 1 to change, 0 to destroy.

Use case 4: Specify values for input variables

Code:

terraform plan -var 'name1=value1' -var 'name2=value2'

Motivation: Input variables allow you to parameterize your infrastructure configuration, making it more flexible. By specifying values for input variables using the -var flag with terraform plan, you can preview the execution plan with custom values for those variables.

Explanation: The -var flag with terraform plan allows you to set values for input variables defined in your Terraform configuration files. These variables represent dynamic values that can be different across environments or deployments. By using this flag, you can generate an execution plan with specific values for those variables.

Example output:

Terraform will perform the following actions:

  # aws_instance.example will be updated in-place
  ~ resource "aws_instance" "example" {
      ~ ami           = "ami-0c94855ba95c71c99" -> "ami-0123456789abcdef0"
      ~ instance_type = "t2.micro"               -> "t3.micro"
      ~ subnet_id     = "subnet-1234567890"      -> "subnet-0987654321"
    }

Plan: 0 to add, 1 to change, 0 to destroy.

Use case 5: Focus Terraform’s attention on only a subset of resources

Code:

terraform plan -target resource_type.resource_name[instance index]

Motivation: When working with large Terraform configurations, it can be time-consuming to generate the execution plan for all resources. By using the -target flag with terraform plan, you can narrow down the focus to a specific resource or a subset of resources, saving time and resources.

Explanation: The -target flag with terraform plan allows you to specify a specific resource or a subset of resources that you want Terraform to focus on. By using the resource type, resource name, and an instance index (if applicable), you can generate an execution plan that only includes changes related to those resources.

Example output:

Terraform will perform the following actions:

  # aws_instance.example will be updated in-place
  ~ resource "aws_instance" "example" {
      ~ ami           = "ami-0c94855ba95c71cbd" -> "ami-0123456789abcdef0"
      ~ instance_type = "t2.micro"               -> "t3.micro"
    }

Plan: 0 to add, 1 to change, 0 to destroy.

Use case 6: Output a plan as JSON

Code:

terraform plan -json

Motivation: If you need the execution plan in a machine-parseable format or if you want to integrate it into other tools or scripts, using the -json flag with terraform plan is useful. It outputs the plan in a JSON format that can be easily consumed by other applications.

Explanation: The -json flag with terraform plan provides the execution plan output in a machine-readable JSON format. This makes it easier to parse and integrate with external tools or scripts that can consume JSON output. It includes all the necessary details about the changes that Terraform will make to the infrastructure.

Example output:

{
  "format_version": "0.1",
  "terraform_version": "1.0.4",
  "planned_values": { ... },
  "resource_changes": [ ... ],
  "configuration": { ... },
  ...
}

Use case 7: Write a plan to a specific file

Code:

terraform plan -no-color > path/to/file

Motivation: Sometimes you might want to save the execution plan to a file for reference or to share with other team members. By using the -no-color flag with terraform plan and redirecting the output to a file, you can save the plan to a specific location.

Explanation: The -no-color flag with terraform plan disables color output, making it easier to read, parse, or process the plan. By redirecting the output to a file using the > operator and specifying the desired path, you can save the plan to a specific file location.

Example output (saved to a file):

Terraform will perform the following actions:

  # aws_instance.example will be created
  + resource "aws_instance" "example" {
      + ami           = "ami-0c94855ba95c71c99"
      + instance_type = "t2.micro"
      + subnet_id     = "subnet-1234567890"
    }

  # aws_s3_bucket.example will be created
  + resource "aws_s3_bucket" "example" {
      + bucket = "example-bucket"
      + region = "us-east-1"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

Conclusion:

The terraform plan command is an essential part of the Terraform workflow. It allows you to preview the changes that Terraform will make to your infrastructure before actually applying them. By utilizing the various options and flags provided by terraform plan, you can gain insight into the execution plan, customize input variables, focus on specific resources, and save the plan in different formats for further analysis or integration with other tools.