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: Terraformv0.11reached 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.xand 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 CLIv0.15.4and 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.0andv1.1.1: When upgrading fromv1.0.11to thev1.1.xseries, upgrade directly to at leastv1.1.2. A critical state bug was present in thev1.1.0andv1.1.1releases. You can find more information about this bug advisory.