What is Terraform Dry Run?

In Terraform, a "dry run" refers to the process of previewing the changes your infrastructure code will make before those changes are actually applied. This crucial step is performed using the terraform plan command, which allows you to inspect the execution plan and understand its full impact without modifying your live environment.

When you run terraform plan, it presents you with an execution plan. This plan shows you exactly which resources are going to be created, deleted, or modified based on your Terraform configuration files and the current state of your infrastructure. It's essentially a dry run, giving you a comprehensive overview of what your code will do before you apply it.

Understanding Terraform Dry Run with terraform plan

The terraform plan command is at the heart of Terraform's dry run capability. Its primary purpose is to provide a detailed report of the actions Terraform proposes to take to reach the desired state defined in your configuration files.

By running terraform plan, you gain the ability to:

• See proposed changes: Get a clear, line-by-line breakdown of resource additions, modifications, and deletions.
• Validate configuration: Identify potential errors, misconfigurations, or unintended consequences early in the development cycle.
• Ensure compliance: Verify that the proposed changes align with your organization's security policies and best practices.

Syntax Example:

To perform a dry run, simply navigate to your Terraform project directory and execute:

terraform plan

For more details, you can refer to the official Terraform plan documentation.

Key Benefits of a Terraform Dry Run

Utilizing terraform plan as a dry run offers numerous advantages that enhance safety, efficiency, and collaboration in infrastructure management:

• Preview Changes Accurately: It shows the exact modifications Terraform intends to make, including attribute changes, resource dependencies, and the order of operations.
• Prevent Costly Errors: Catching configuration mistakes or unexpected resource changes before deployment can save significant time, effort, and potential service disruptions.
• Enhance Security & Compliance: Reviewing the plan allows teams to ensure that proposed changes adhere to security policies, regulatory requirements, and internal governance.
• Facilitate Collaboration and Review: The output of terraform plan can be easily shared with team members, allowing for peer review and consensus before any actual infrastructure changes are made.
• Understand Resource Impact: Gain insight into how changes to one resource might cascade and affect others, helping to understand the complete system impact.

How terraform plan Works

The terraform plan command executes a series of steps to generate its comprehensive output:

1. Refresh State: Terraform first connects to your cloud provider(s) (e.g., AWS, Azure, GCP) to refresh its understanding of the current infrastructure state. This ensures the plan is based on the most up-to-date reality.
2. Compare Configuration: It then compares the refreshed state with the desired state defined in your .tf configuration files.
3. Generate Plan: Based on this comparison, Terraform determines the necessary actions (create, update, or delete resources) required to reconcile the current state with the desired state.
4. Display Output: Finally, it presents this proposed execution plan to the user in a human-readable format, using symbols like + (create), ~ (update), and - (destroy) to indicate actions.

Practical Examples and Scenarios

Let's look at how terraform plan behaves in different scenarios:

Scenario 1: Adding a New Resource

If you add a new resource block to your Terraform configuration, terraform plan will show it as an addition.

Example Code (main.tf):

resource "aws_s3_bucket" "my_new_bucket" {
  bucket = "my-unique-new-bucket-name-12345"
  acl    = "private"

  tags = {
    Environment = "Dev"
    Project     = "Example"
  }
}

terraform plan Output Description:

Terraform will perform the following actions:

  # aws_s3_bucket.my_new_bucket will be created
  + resource "aws_s3_bucket" "my_new_bucket" {
      + acl                         = "private"
      + arn                         = (known after apply)
      + bucket                      = "my-unique-new-bucket-name-12345"
      ...
    }

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

Scenario 2: Modifying an Existing Resource

When you change an attribute of an already provisioned resource, terraform plan will show it as a modification.

Example Code (modifying tags):

resource "aws_s3_bucket" "my_new_bucket" {
  bucket = "my-unique-new-bucket-name-12345"
  acl    = "private"

  tags = {
    Environment = "Development" # Changed from "Dev"
    Project     = "Example"
    ManagedBy   = "Terraform"   # New tag
  }
}

terraform plan Output Description:

Terraform will perform the following actions:

  # aws_s3_bucket.my_new_bucket will be updated in-place
  ~ resource "aws_s3_bucket" "my_new_bucket" {
        id                          = "my-unique-new-bucket-name-12345"
        tags                        = {
      ~ "Environment" = "Dev" -> "Development"
      + "ManagedBy"   = "Terraform"
            "Project"     = "Example"
        }
        # (2 unchanged attributes hidden)
    }

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

Scenario 3: Deleting a Resource

If you remove a resource block from your configuration, terraform plan will indicate its destruction.

Example Code (removing aws_s3_bucket):

(Assuming the aws_s3_bucket.my_new_bucket resource block is entirely removed from main.tf)

terraform plan Output Description:

Terraform will perform the following actions:

  # aws_s3_bucket.my_new_bucket will be destroyed
  - resource "aws_s3_bucket" "my_new_bucket" {
      - acl                         = "private" -> null
      - arn                         = "arn:aws:s3:::my-unique-new-bucket-name-12345" -> null
      - bucket                      = "my-unique-new-bucket-name-12345" -> null
      ...
    }

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

Advanced terraform plan Features

terraform plan offers additional options for more complex scenarios:

• terraform plan -out=filename: Saves the generated plan to a specified file. This plan file can then be used with terraform apply filename to ensure that only the exact changes previewed are applied, which is particularly useful in CI/CD pipelines.
• terraform plan -var="key=value": Allows you to pass variable values directly from the command line, overriding those defined in .tfvars files or environment variables.
• terraform plan -destroy: Generates a plan that shows all resources that would be destroyed if you were to run terraform destroy. This is a critical dry run for decommissioning infrastructure.
• terraform plan -target=resource_type.name: Focuses the plan on a specific resource, useful for testing isolated changes. (Use with caution in production as it can lead to state drift).

terraform plan vs. terraform apply

It's essential to understand the distinct roles of terraform plan and terraform apply:

Feature	terraform plan (Dry Run)	terraform apply
Purpose	Preview changes, validate configuration	Execute changes, provision infrastructure
Action	Read-only, no infrastructure modification	Modifies actual infrastructure
Safety	High, safe to run multiple times	Requires careful review before confirmation
Output	Proposed actions (+, ~, -)	Actual changes and final state
Interaction	Does not require user confirmation	Prompts for user confirmation by default

In summary, terraform plan is your safeguard, providing a clear forecast of changes, while terraform apply is the execution engine that makes those changes a reality. Always perform a terraform plan before an apply to ensure predictable and controlled infrastructure management.