Manage Terraform versions

HashiCorp actively develops and maintains Terraform. To access new Terraform features you need to upgrade the version of Terraform that your configurations use. Set the required_version to control the version of Terraform that your configurations use and 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 1.2 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.

$ git clone https://github.com/hashicorp/learn-terraform-versions.git

Change into the directory.

$ cd learn-terraform-versions

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 terraform.tf, and review the terraform block.

terraform {
  required_providers {
    aws = {
      version = "~> 5.52.0"
    }
    random = {
      version = "~> 3.6.2"
    }
  }

  required_version = "~> 1.1.9"
}

This configuration sets required_version to ~> 1.1.9. The ~> symbol allows the patch version to be greater than 9 but requires the major and minor versions (1.1) to match the version that the configuration specifies. Terraform will error if you attempt to use this configuration with a more recent version than 1.1.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 version
Terraform v1.7.5
on darwin_arm64

Your version of Terraform is out of date! The latest version
is 1.8.4. You can update by downloading from https://www.terraform.io/downloads.html

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.

$ terraform init

Initializing the backend...
╷
│ Error: Unsupported Terraform Core version
│ 
│   on terraform.tf line 11, in terraform:
│   11:   required_version = "~> 1.1.9"
│ 
│ This configuration does not support Terraform version 1.7.5. To proceed, either choose another supported Terraform version or update this version constraint.
│ Version constraints are normally set for good reason, so updating the constraint may lead to other errors or unexpected behavior.
╵

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 terraform.tf, replace 1.1.9 with your current Terraform version, as printed out by the terraform version command. Be sure to save the file.

terraform {
  required_providers {
## ...
  }

  required_version = "~> <TERRAFORM_VERSION>"
}

Now initialize your configuration.

$ terraform init

Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/aws versions matching "~> 5.52.0"...
- Finding hashicorp/random versions matching "~> 3.6.2"...
- Installing hashicorp/random v3.6.2...
- Installed hashicorp/random v3.6.2 (signed by HashiCorp)
- Installing hashicorp/aws v5.52.0...
- Installed hashicorp/aws v5.52.0 (signed by HashiCorp)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Apply this configuration now to create the example infrastructure. Remember to respond to the confirmation prompt with a yes.

$ terraform apply
data.aws_ami.amazon_linux: Reading...
data.aws_ami.amazon_linux: Read complete after 1s [id=ami-0676a735c5f8e67c4]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # aws_instance.web will be created
  + resource "aws_instance" "web" {
      + ami                                  = "ami-0676a735c5f8e67c4"
      + arn                                  = (known after apply)
## ...

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

application_url = "ec2-35-94-148-223.us-west-2.compute.amazonaws.com/index.php"
domain_name = "ec2-35-94-148-223.us-west-2.compute.amazonaws.com"

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.

$ grep -e '"version"' -e '"terraform_version"' terraform.tfstate
  "version": 4,
  "terraform_version": "1.7.5",

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.

$ terraform apply

Error: Error locking state: Error acquiring the state lock: state snapshot was
created by Terraform v1.7.5, which is newer than current v0.12.29; upgrade to
Terraform v1.7.5 or greater to work with this state

Terraform acquires a state lock to protect the state from being written
by multiple users at the same time. Please resolve the issue above and try
again. For most commands, you can disable locking with the "-lock=false"
flag, but this is not recommended.

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.

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.

$ terraform destroy
random_pet.name: Refreshing state... [id=ruling-sunbeam]
data.aws_ami.amazon_linux: Reading...
data.aws_ami.amazon_linux: Read complete after 1s [id=ami-0676a735c5f8e67c4]
aws_instance.web: Refreshing state... [id=i-0711f6d7f58958fea]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  - destroy

Terraform will perform the following actions:

  # aws_instance.web will be destroyed
  - resource "aws_instance" "web" {
      - ami                                  = "ami-0676a735c5f8e67c4" -> null
      - arn                                  = "arn:aws:ec2:us-west-2:949008909725:instance/i-0711f6d7f58958fea" -> null
## ...
Plan: 0 to add, 0 to change, 2 to destroy.

Changes to Outputs:
  - application_url = "ec2-35-94-148-223.us-west-2.compute.amazonaws.com/index.php" -> null
  - domain_name     = "ec2-35-94-148-223.us-west-2.compute.amazonaws.com" -> null

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

aws_instance.web: Destroying... [id=i-0711f6d7f58958fea]
aws_instance.web: Still destroying... [id=i-0711f6d7f58958fea, 10s elapsed]
aws_instance.web: Still destroying... [id=i-0711f6d7f58958fea, 20s elapsed]
aws_instance.web: Still destroying... [id=i-0711f6d7f58958fea, 30s elapsed]
aws_instance.web: Still destroying... [id=i-0711f6d7f58958fea, 40s elapsed]
aws_instance.web: Destruction complete after 41s
random_pet.name: Destroying... [id=ruling-sunbeam]
random_pet.name: Destruction complete after 0s

Destroy complete! Resources: 2 destroyed.

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.

HCP Terraform 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 HCP Terraform or Terraform Enterprise, you can configure each HCP Terraform 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.