Intro

This guide will walk you through how to update any code that depends on the Gruntwork Infrastructure as Code Library to Terraform 1.x. Terraform v1.0 is an unusual release in that its primary focus is on stability. Terraform v1.0.0 intentionally has no significant changes compared to Terraform v0.15.5. You can consider the v1.0 series as a direct continuation of the v0.15 series.

What you’ll learn in this guide

This guide consists of two main sections:

Core Concepts

An overview of Terraform 1.x.

Deployment walkthrough

The steps you need to take to update your code relying on the Gruntwork Infrastructure as Code library to work with Terraform 1.x. Includes a version compatibility table you can use as a reference to know which Gruntwork Repo version tag is compatible with Terraform 0.15.

Core Concepts

Background

Terraform 1.0.0 was released on June 08, 2021. Some of the major new features in 0.15 include:

  1. A more stable state file format that will be compatible with Terraform 0.14, 0.15, and, once it’s released, 1.0.

For more info, check out the for a complete introduction, check out the announcement blog post.

From the release notes: "Terraform v1.0.0 intentionally has no significant changes compared to Terraform v0.15.5. You can consider the v1.0 series as a direct continuation of the v0.15 series; we do not intend to issue any further releases in the v0.15 series, because all of the v1.0 releases will be only minor updates to address bugs."

Deployment walkthrough

Step 1: update your code to be compatible with Terraform 0.15

If you haven’t already, you need to:

  1. Update your code to work with Terraform 0.15. Do NOT skip from, say, 0.11, straight to 1.x. You MUST update to 0.15.0 or above first!

    1. If you’re still on Terraform 0.11 or older, see our Terraform 0.12 upgrade guide.

    2. If you’re still on Terraform 0.12, see our Terraform 0.13 upgrade guide.

    3. If you’re still on Terraform 0.13, see our Terraform 0.14 upgrade guide.

    4. If you’re still on Terraform 0.14, see our Terraform 0.15 upgrade guide.

  2. Update all your Gruntwork modules to the latest versions just before the TF 1.x versions in the compatibility table below. The upgrade will be much easier and less error prone if you keep the number of version jumps as small as possible.

Step 2: update references to the Gruntwork Infrastructure as Code Library

In order to take advantage of the Terraform 1.x, you need to update your references to the Gruntwork Infrastructure as Code Library to use a compatible version. We (Gruntwork) have gone through all our modules in the library to test and update the code to be compatible with Terraform 1.x. As a customer, you need to update to the proper versions of the Gruntwork library to pick up the fixes/changes that we made to be compatible. Refer to the "Updating" section of "How to use the Gruntwork Infrastructure as Code Library" for instructions on how to update the versions in your code.

For the vast majority of the repos, the only change that will be necessary is a version number bump, but several repos require more extensive code changes and state migrations. To upgrade without downtime and data loss, you MUST follow the migration instructions in the release notes in each repo to know what changes need to be made to update to the new version.

Important
Gruntwork follows semantic versioning. For any pre-1.0 modules, this means that version updates to the minor version are considered backwards incompatible releases for any version updates prior to 1.0.0 release. Make sure to read the release notes for the relevant modules any time you are updating minor versions! Note that you will want to read the release notes for each minor version that is updated (e.g., if you are going from v0.5.x to v0.9.x, you will want to read the notes for v0.6.0, v0.7.0, v0.8.0, and v0.9.0 to get the full list of backwards incompatible updates).

The following table provides a summary of all the relevant Gruntwork AWS modules and the respective versions that are compatible with Terraform 1.x:

Gruntwork Repo Minimum version with Terraform 1.x support

Terratest

v0.37.0

Terragrunt

v0.31.0

terraform-aws-utilities

v0.6.0

terraform-aws-vpc

v0.17.0

terraform-aws-asg

v0.15.0

terraform-aws-server

v0.13.0

terraform-aws-lambda

v0.13.0

terraform-aws-security

v0.53.0

terraform-aws-load-balancer

v0.27.0

terraform-aws-data-storage

v0.21.0

terraform-aws-cache

v0.16.0

terraform-aws-messaging

v0.7.0

terraform-aws-static-assets

v0.11.0

terraform-aws-monitoring

v0.30.0

terraform-aws-openvpn

v0.16.0

terraform-aws-ecs

v0.30.0

terraform-aws-ci

v0.38.0

terraform-aws-eks

v0.43.0

terraform-aws-zookeeper

v0.12.0

terraform-aws-kafka

v0.11.0

terraform-aws-elk

v0.11.0

terraform-kubernetes-namespace

v0.4.0

terraform-aws-cis-service-catalog

v0.26.0

terraform-aws-sam

v0.6.0

terraform-aws-couchbase

v0.7.0

terraform-aws-vault

v0.17.0

terraform-aws-consul

v0.11.0

terraform-aws-nomad

v0.10.0

terraform-aws-architecture-catalog

v0.0.18

terraform-aws-service-catalog

v0.55.0