Manage Terraform Versions
HashiCorp and a community of open source contributors actively develop and
maintain the Terraform CLI. As you use Terraform, you will often have the
opportunity to upgrade to the latest version to receive the benefits of new
features. Use the required_version
setting to control when you upgrade the
version of Terraform that you use for your Terraform projects to make updates
more predictable.
In this tutorial, you will update an existing configuration to use the latest version of Terraform and learn how to manage different versions of Terraform within a team.
Prerequisites
You will need the following to complete this tutorial:
- The Terraform CLI, version 0.15 or later, installed locally.
- An AWS account.
- Your AWS credentials configured locally with your access keys and a default region.
- The git CLI.
Clone example repository
Clone the example GitHub repository for this tutorial.
Change into the directory.
This repository contains a complete Terraform configuration that deploys an example web application on AWS. However, this configuration uses an older version of Terraform. You will update it to use a more recent version of Terraform.
Review example configuration
Open main.tf
, and find the terraform
block.
This configuration sets required_version
to ~> 0.12.29
. The ~>
symbol allows the patch version to be greater than 29
but requires the major
and minor versions (0.12
) to match the version that the configuration
specifies. Terraform will error if you attempt to use this configuration with a
more recent version than 0.12.x
, because of this required_version
setting.
Use the version
subcommand to check your Terraform version and the
version of any providers your configuration is using.
Terraform will also let you know if there is a newer version of Terraform available.
Attempt to initialize your project with terraform init
. Terraform will print
out an error telling you that your local version of Terraform is too new for
this configuration's required_version
constraint.
HashiCorp uses the format major.minor.patch
for Terraform versions. HashiCorp
updates Terraform frequently, so it is common to use configuration
written for an earlier version of Terraform. New minor and patch versions of
Terraform are backward compatible with configuration written for previous
versions. Because of this, you can upgrade to a newer minor version of Terraform
and still use your existing configurations. However, upgrading your Terraform
version can have other consequences, such as requiring you to update your
provider versions. Some version updates may refresh your state file version or require configuration file edits to implement new features. Use
the required_version
setting to control which versions of Terraform will work
with your configurations to ensure that updates to your infrastructure are safe
and predictable.
In main.tf
, replace 0.12.29
with your current Terraform version, as printed
out by the terraform version
command. Be sure to save the file.
Now initialize your configuration.
Apply this configuration now to create the example infrastructure. Remember to
respond to the confirmation prompt with a yes
.
Inspect the Terraform state file
When you run Terraform commands, Terraform stores its current version in your project's state file, along with the state file version format. Since Terraform stores its state file as text, you can inspect the state to determine which version of Terraform generated it.
Tip
If your system does not have the grep
command, you can open the
terraform.tfstate
file in your text editor to review the values of
version
and terraform_version
near the beginning of the file.
Terraform will only update the state file version
when a new version of Terraform requires a change to the state file's format. Terraform
will update the terraform_version
whenever you apply a change to your
configuration using a newer Terraform version.
In general, Terraform will continue to work with a given state file across minor version updates. For major or minor releases, Terraform will update the state file version if required, and give an error if you attempt to run an older version of Terraform using an unsupported state file version.
If you were to attempt to apply this configuration again using an older version of Terraform that does not support the current state file version, Terraform returns a state lock error and displays the necessary version.
Once you use a newer version of Terraform's state file format on a given project, there is no supported way to revert to using an older state file version.
Terraform manages provider versions independently of the version of Terraform itself. Sometimes an older version of a provider will not work with a newer version of Terraform. Whenever you upgrade Terraform, review your provider versions and consider upgrading them as well. Try our tutorial on locking and upgrading provider versions to learn how to manage provider versions.
Terraform version constraints
The following table summarizes some of the ways you can pin the Terraform
version in the required_version
setting, assuming Terraform v0.15.0 as your
current target version. Refer to the Terraform
documentation
for a detailed explanation of version constraints.
Required Version | Meaning | Considerations |
---|---|---|
0.15.0 | Only Terraform v0.15.0 exactly | To upgrade Terraform, first edit the required_version setting |
>= 0.15 | Any Terraform v0.15.0 or greater | Includes Terraform v1.0.0 and above |
~> 0.15.0 | Any Terraform v0.15.x, but not v1.0 or later | Minor version updates are intended to be non-disruptive |
>= 0.15, < 2.0.0 | Terraform v0.15.0 or greater, but less than v2.0.0 | Avoids major version updates |
In general, we encourage you to use the latest available version of Terraform to take advantage of the most recent features and bug fixes. However, it is unnecessary to upgrade your Terraform projects to the latest version every time you use Terraform unless you need a specific feature or bug fix.
As a best practice, consider using ~>
style version constraints to pin your
major and minor Terraform version. Doing so will allow you and your team to use
patch version updates without updating your Terraform configuration. You can
then plan when you want to upgrade your configuration to use a new version of
Terraform, and carefully review the changes to ensure that your project still
works as intended.
For example, if you write Terraform configuration using Terraform 1.0.0, you
would add required_version = "~> 1.0.0"
to your terraform { }
block. This
will allow you and your team to use any Terraform 1.0.x
, but you will need to
update your configuration to use Terraform 1.1.0
or later.
Clean up your infrastructure
Destroy the infrastructure you created in this tutorial. Respond to the
confirmation prompt with a yes
.
Next steps
Now you have managed Terraform versions using the Terraform CLI. When using Terraform in production, we strongly recommend that you and your team have plans and procedures in place to determine how you will manage Terraform versions and handle upgrades.
Terraform Cloud and Terraform Enterprise include features that help teams work together on Terraform projects, such as providing a managed execution environment for Terraform and support for teams and permissions. When you use Terraform Cloud or Terraform Enterprise, you can configure each Terraform Cloud workspace to use whichever version of Terraform you specify.
For more information on topics covered in this tutorial, check out the following resources.
- Manage Terraform versions in Terraform Cloud tutorial.
- Terraform version constraints documentation for a detailed explanation of version constraints.
- Lock and Upgrade Provider Versions tutorial.