Terraform 0.14 Adds a New Concise Diff Format to Terraform Plans

[Hashicorp]

The upcoming HashiCorp Terraform 0.14 release includes a new, experimental, on-by-default, concise diff renderer. This small but significant new behavior is designed to help practitioners quickly understand what changes Terraform is about to make to existing infrastructure. 

Background

Terraform 0.12 introduced a new plan file format and structural diff renderer, which was a significant change from 0.11. Most notably, for updated resources, Terraform moved from showing only the changed attribute path/values, to showing the entire resource with changed values prefixed with ~.

For plans which slightly change existing resources, this can result in very large diffs which make it difficult to reason about the actual changes.

Diff Renderer Design

The diff renderer used by terraform plan, terraform apply, and terraform show <planfile> has been updated to hide unchanged and irrelevant fields. This means:

• Always show all identifying fields, initially defined as id, name, and tags, even if unchanged
• Only show changed, added, or removed primitive values: string, number, or bool
• Only show added or removed elements in unordered collections and structural types: map, set, and object
• Show added or removed elements with up to two contextual unchanged elements for sequence types: list and tuple
• Only show added or removed nested blocks, or blocks with changed attributes

If any attributes, collection elements, or blocks are hidden, a count will be kept and displayed at the end of the parent scope. This ensures that the diff is clearly only displaying a subset of the resource.

Diff Rendering Details

Changed primitive values will render as before: prefixed with a ~, and showing the old and new value. Any hidden attributes will be counted, and the total displayed at the end of the resource:

~ attribute_name   = "old value" -> "new value"
  # (12 unchanged attributes hidden)

Unordered collections (sets or maps) with added or removed elements will use the same approach:

~ regions = [
    - "us-east-1",
    - "us-west-2",
    + "eu-west-1",
    + "eu-west-2",
      # (1 unchanged element hidden)
  ]

Sequences (lists or tuples) will display context around changes:

~ words     = [
      # (3 unchanged elements hidden)
    - "delta",
    + "data",
      "echo",
      # (5 unchanged elements hidden)
      "kilo",
    - "Lima",
    + "London",
      "Mike",
      " (13 unchanged elements hidden)
  ]

Any nested blocks for a resource that are unchanged will also be counted and the total displayed:

# (3 unchanged blocks hidden)

When color is enabled, these hidden value counts will be displayed in a lower-contrast color.

Diff Examples

Changes to attributes:

  # test_resource.foo will be updated in-place
  ~ resource "test_resource" "foo" {
        id       = "foo_123"
      ~ checksum = 28987129 -> (known after apply)
      - mode     = "test" -> null
        name     = "Foo Test"
        tags     = []
      ~ totals   = {
          - "bar" = 5 -> null
          + "baz" = 5
              # (2 unchanged elements hidden)
        }
      ~ values   = [
          - "alpha",
          - "gamma",
          + "alpaca",
          + "goblin",
          + "zephyr",
            # (23 unchanged elements hidden)
        ]
        # (5 unchanged attributes hidden)

        # (3 unchanged blocks hidden)
    }

Adding a new block:

  # test_resource.foo will be updated in-place
  ~ resource "test_resource" "foo" {
        id       = "foo_123"
      ~ checksum = 28987129 -> (known after apply)
        name     = "Foo Test"
        tags     = []
        # (8 unchanged attributes hidden)

      + sub_item {
          + identifier = "bar"
          + size       = 4
          + type       = "whatever"
        }
        # (3 unchanged blocks hidden)
    }

Getting Started with the Terraform 0.14 Beta

Here is where to find important getting started information about Terraform 0.14:

• The Terraform 0.14 beta guide
• Beta documentation for sensitive input variables
• Beta documentation for the depency lock file

To get started using Terraform 0.14:

• Download the latest Terraform 0.14 beta release.
• If you are upgrading from a previous release, read the draft upgrade guide to learn about taking advantage of Terraform 0.14’s new features

As with all pre-release builds, remember that v0.14.0-beta1 may still contain bugs and it should not be used in a production setting. We welcome your feedback on the beta. If you run into an issue, please file a new bug report in GitHub. Please check the known issues list before filing to see if your issue has already been reported.

To evaluate Terraform 0.14 betas as part of your Terraform Cloud workflow, please write to support@hashicorp.com to have Terraform beta access added to your organization.

View the full article