Upgrading Terraform: Why and how to?

Andres Varela | July 05, 2022


When we talk about Infrastructure as code (IaC) tools, Terraform might be the first that comes to mind. It has allowed us to create and manage all kinds of cloud resources by integrating our code files with the provider’s APIs.

Terraform has released several versions since the first one in 2014, and the evolution has significantly improved the functionality. It’s important to keep Terraform updated with major releases if we want to make the most of it.

The differences between Terraform versions are usually syntax, behavior, and feature-support related. Syntax related changes are the most common ones that you’ll have to deal with when upgrading from Terraform 0.13.x or lower. This is because the HCL (Hashicorp Configuration Language) syntax has gone through significant changes.

Why should you upgrade your Terraform version?

Like any other software tool, library or platform, every new patch or release comes with improvements, bug fixes, and most importantly, security fixes. This also applies to Terraform, and is the main reason to consider upgrading the tool that you use to manage your whole cloud infrastructure with.

Also, regardless of the pace of your project/organization to grow or modify its cloud-based infrastructure, you will eventually need to reprovision it, to be able to include new resources or features. If you do this frequently, it is easier to keep up to date with syntax and supported attributes for each new resource you include, since you would be most likely using the latest modules with non-deprecated attributes. On the other hand, if there is no regular provisioning, you might not be aware of the need for an upgrade until you need to include some new feature that require an upgrade. In this scenario, the impact would be a lot larger.

Before you start, keep this in mind:

The instructions that need to be followed to upgrade between Terraform releases might depend on which version you are upgrading from. Terraform provides a full upgrade guide on the features, breaking changes, and compatibility issues you might need to consider in each case.

It is strongly recommended to perform one major release upgrade at a time, and not to skip intermediate ones. For instance, if you need to go from v0.13 to v0.15, you should first upgrade to the latest major v0.13.x release until you reach v0.14 and followed by similar iterative upgrades to v0.15, instead of jumping straight to v0.15. This is all described in the official guides for the release you may need to use.

Here is a sample set of recommendations for upgrading, in this case, to Terraform v1.0:

Picture1-Jul-05-2022-05-32-01-81-PMRecommendations for upgrading to Terraform v1.0

How to do it?

  • In general terms, the basic upgrading process for each release jump can be summarized as: Setup a local environment with the Terraform version to upgrade. Keep in mind you’ll have to work with different versions and switch between them, so I would advise you to use a tool such as tfenv, or to use the official Terraform docker image for a container, corresponding to the version you need. This could help you isolate the environment you work with for every release.
  • Before jumping to the next version, execute one last Terraform plan on your current version and (optionally) work on fixing the deprecation warnings you already have.
  • Perform a Terraform plan. This will show you what Terraform is detecting on your code that must be modified in order to comply with the syntax and fix all warnings. If the current configuration executes a breaking change, some resources might be recreated.
  • Once you have fixed all warnings, and you have a “clean” Terraform plan (except you have made changes that will inevitably modify your resources, and you are aware of that), you may now perform a terraform apply. Even if there isn’t any resource modifications, this will update the Terraform version in the remote tfstate.


This flowchart summarizes the above steps:


Key Takeaways

  • Even if current Terraform configurations are working fine, eventually Terraform would need to be upgraded. The longer you wait, the harder it’ll get to upgrade, don’t let your infrastructure get stuck in a terraform version.
  • You may skip some minor versions in the upgrade process, but ensure that the Terraform upgrade guides specify that it is safe to do so.
  • As always, be careful with the changes your terraform plan is perceiving, try to keep them at minimum and be aware of replacements or re-deployment of resources.
  • Keep track of your tfstate (remote if you have one). This is your infrastructure configuration.
  • Make sure everyone in your team is aware of the upgrade you just performed. They won’t be able to initialize their Terraform environment if they use the previous version.

About Encora

Fast-growing tech companies partner with Encora to outsource product development and drive growth. Contact us to learn more about our software engineering capabilities.

Join Us at Encora

Are you a developer or engineer looking to make an impact on the world through technology? Visit Encora careers to join a passionate community of innovators and receive unmatched opportunities for professional development and benefits.

Insight Content


Share this Post

Featured Insights

Fill Out Later