Terraform Upgrade Best Practices

Problem

Introduction

When upgrading Terraform, you should consult the official upgrade guide for each version you plan to adopt. For a detailed list of feature improvements and bug fixes in each release, refer to the Terraform CHANGELOG. You can download specific Terraform binary releases from the official releases page.

Scenario

You need to upgrade your version of Terraform, potentially across one or more major versions.

Recommendation

General Principles

Before upgrading between major releases, it is crucial to execute a terraform plan that results in no proposed changes. Pending changes can introduce additional unknown variables to the upgrade process. Note that completing the upgrade will require running a successful terraform apply with your target version.

Recommended Upgrade Path

Terraform versions can be grouped into the following series:

• v0.1 - v0.11: Terraform v0.11 reached End-of-Life (EOL) on May 1st, 2021, and is no longer supported by HashiCorp.
• v0.12 - v0.13
• v0.14 - v1.0
• v1.0 - v1.2.x and later

Based on our official documentation, follow this upgrade path to reach the stable v1.x series:

If you are currently using Terraform v0.13, we strongly recommend upgrading one major version at a time until you reach v0.14. Follow the upgrade guides for each intermediate version. These earlier versions include mechanisms to automatically detect and, in some cases, apply necessary configuration changes.

Once you reach Terraform v0.14, you can then upgrade directly to v1.0.

Important Considerations

• Dependency Graph in v0.15.4: Terraform CLI v0.15.4 and newer resolved an issue with the resource dependency graph algorithm that could cause unexpected resource recreation. However, you should still review the notes in the Terraform v0.15 upgrade guide in full.
• State Bug in v1.1.0 and v1.1.1: When upgrading from v1.0.11 to the v1.1.x series, upgrade directly to at least v1.1.2. A critical state bug was present in the v1.1.0 and v1.1.1 releases. You can find more information about this bug advisory.

Additional Information

• How to find the right documentation for any Terraform version
• Failed to install provider after upgrading to Terraform 0.14
• Plugin reinitialization error after upgrade to Terraform 0.13