Upgrade Terraform version in Terraform Cloud

Each Terraform Cloud workspace has an assigned Terraform version that it uses for all remote operations in the workspace. Configuring the Terraform version ensures consistent behavior across runs, making it easy to collaborate on infrastructure management. When you decide to upgrade Terraform, Terraform Cloud provides workflows that allow you to verify the change safely.

In this tutorial, you will update a Terraform Cloud-managed configuration from Terraform 0.12 to 0.13, using Terraform Cloud’s speculative plan to validate the upgrade and the empty apply run to upgrade the state version.

Prerequisites

The tutorial assumes that you are familiar with the Terraform and Terraform Cloud workflows. If you are new to Terraform itself, refer first to the Getting Started tutorials. If you are new to Terraform Cloud, refer to the Get Started - Terraform Cloud tutorials.

To complete this tutorial, you will need:

• A Terraform Cloud account.
• An AWS account

Fork example repository

Fork the example repository for this tutorial. You will connect this repository to a Terraform Cloud workspace.

The example configuration deploys a web application on AWS. However, this configuration uses an old version of Terraform. You will update it to use a more recent version of Terraform.

Create a workspace

Click the + New workspace button to create a new workspace.

Configure your workspace:

1. Choose "Version control workflow".
2. For the version control provider, choose "GitHub". If this is the first time you have configured a workspace with GitHub, Terraform Cloud will prompt you to authenticate with your GitHub account.
3. Select the learn-terraform-versions repository you forked earlier.
4. Leave the workspace name as-is
5. Expand the Advanced options menu and make sure that Terraform Cloud enabled Automatic speculative plans.
6. Create your workspace.

Click Continue to workspace overview to navigate to your workspace.

Update workspace version

The configuration in your forked repository uses a version constraint to ensure that operators use Terraform 0.12 for any Terraform runs. However, your Terraform Cloud workspace is configured to use the latest version, as displayed in your workspace details.

When you create a new workspace, Terraform Cloud automatically selects the most recent version of Terraform available. If you migrate an existing project from the CLI to Terraform Cloud, Terraform Cloud configures the workspace to use the same version as the Terraform binary you used when migrating. Terraform Cloud lets you change the version a workspace uses on the workspace's settings page to control how and when your projects use newer versions of Terraform.

Click on the workspace version to go to the workspace’s general settings page, then scroll down to the version selector. Select version 0.12.31 to satisfy your configuration’s version constraint. Then, click Save settings.

Create infrastructure

Trigger a new Terraform run by selecting Start new run from the Actions menu in your workspace. Click Start run. Then, click Confirm & Apply to create your resources.

At this point, your example workspace is in good working condition, but uses an outdated Terraform version.

Update version constraint in Terraform configuration

Your current Terraform configuration only works with Terraform versions in the 0.12 series. To upgrade your project, you will need to modify both the workspace version and the version constraint in your configuration.

Clone your fork of the tutorial repository, replacing USERNAME with your GitHub username.

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

Change to the repository directory.

$ cd learn-terraform-versions

Open main.tf and update the required_version constraint to ~> 0.13.0.

terraform {
  required_providers {
    aws = {
      version = "~> 4.0"
    }
    random = {
      version = ">= 2.1.2"
    }
  }

  required_version = "~> 0.13.0"
}

To verify that your configuration is still valid using the new Terraform version, you will open a pull request in the repository to trigger a speculative plan.

First, create a new branch.

$ git checkout -b upgrade_terraform_013

Stage your changes.

$ git add .

Commit your changes.

$ git commit -m "Upgrade version constraint to Terraform 0.13"

Finally, push your changes.

$ git push -u origin upgrade_terraform_013

Test new Terraform version

In the GitHub web UI, open a new pull request for your changes against your fork of the repository. Once you open the pull request, Terraform Cloud will create a speculative plan to demonstrate the changes in the pull request. Since you updated the version constraint in your configuration, but your Terraform Cloud workspace still uses version 0.12.31, the plan will fail.

Click on the Details link next to the failed plan to see the plan details in Terraform Cloud. As expected, the output shows that the Terraform version used for the plan does not satisfy the configuration.

Though Terraform uses the version configured for your workspace for normal Terraform runs, you can select a specific version of Terraform to use for a speculative plan to test version-sensitive changes.

Select version 0.13.7 from the dropdown menu below the run output, then click Retry run to verify that your configuration works with a newer Terraform version.

In the plan details, Terraform Cloud indicates that you used a different version for this plan than the version configured for the workspace. The run succeeds and shows no planned changes, confirming that your configuration is compatible with Terraform 0.13.

Update workspace Terraform version

On the Terraform Cloud workspace settings page, update your workspace's version to 0.13.7 and save the change.

Then, merge your pull request to update the version constraint on your main branch.

Your merged pull request does not modify your resources, so Terraform will trigger and complete the run automatically. It will not ask you to apply your configuration in order to upgrade the state since there are no changes. If you inspect the latest state file stored in the workspace, it still shows state version 4 and Terraform version 0.12.31.

Perform an apply to finish upgrading

Although your workspace can now use Terraform 0.13 for runs, the upgrade is incomplete. Terraform 0.13 introduced changes to the state file format, so you must apply a run within the workspace to update the state version and complete the upgrade.

Terraform Cloud does not apply runs without resource changes by default, but it provides the empty apply run type to assist with major version upgrades.

Trigger an empty apply run by selecting Start new run from the workspace Actions menu, then select Allow empty apply in the run type dropdown. Then, click Start run.

The empty apply run type allows Terraform Cloud to update your state version despite the fact that there are no changes to make to your resources.

Confirm and apply the empty run, and Terraform Cloud will update your workspace’s state file to reflect the new Terraform version.

Now, inspect the most recent state file for your workspace. Terraform Cloud updated the Terraform version in the state file to 0.13.7.

Now you have updated your configuration to use Terraform 0.13 instead of 0.12, and updated your Terraform Cloud workspace’s state file to match. The workspace now meets the minimum state format requirements for Terraform 0.14 and later.

Destroy infrastructure

Now that you have completed the tutorial, destroy the infrastructure you created to avoid incurring unnecessary costs.

First, trigger and approve a destroy run in your learn-terraform-versions workspace. After deleting the resources, delete the workspace as well.

Next steps

In this tutorial, you used different Terraform Cloud run types to test and upgrade the version of Terraform used in a workspace. First, you used the speculative plan with a custom version to verify that your configuration works with a newer Terraform version. Then, you used the empty apply run to safely upgrade the state and version of the workspace.

For more information on topics covered in this tutorial, review the following resources.

• Manage Terraform versions with the Terraform CLI.
• Lock and Upgrade Provider Versions tutorial.
• Terraform version constraints documentation for a detailed explanation of version constraints.