Upgrade Terraform version in HCP Terraform

Each HCP Terraform 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, HCP Terraform provides workflows that allow you to verify the change safely.

In this tutorial, you will update an HCP Terraform-managed configuration from Terraform 0.12 to 0.13, using HCP Terraform’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 HCP Terraform workflows. If you are new to Terraform itself, refer first to the Getting Started tutorials. If you are new to HCP Terraform, refer to the Get Started - HCP Terraform tutorials.

To complete this tutorial, you will need:

• An HCP Terraform account.
• An AWS account

Fork example repository

Fork the example repository for this tutorial. You will connect this repository to an HCP Terraform 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

Create a new workspace:

1. Log in to your HCP Terraform organization.
2. Navigate to the Workspaces page.
3. Click the New dropdown and select Workspace.
4. Select your organization's Default Project and create the 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, HCP Terraform 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 HCP Terraform 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 HCP Terraform workspace is configured to use the latest version, as displayed in your workspace details.

When you create a new workspace, HCP Terraform automatically selects the most recent version of Terraform available. If you migrate an existing project from the CLI to HCP Terraform, HCP Terraform configures the workspace to use the same version as the Terraform binary you used when migrating. HCP Terraform 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

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, HCP Terraform will create a speculative plan to demonstrate the changes in the pull request. Since you updated the version constraint in your configuration, but your HCP Terraform 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 HCP Terraform. 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, HCP Terraform 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 HCP Terraform 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.

HCP Terraform 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 HCP Terraform 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 HCP Terraform will update your workspace’s state file to reflect the new Terraform version.

Now, inspect the most recent state file for your workspace. HCP Terraform 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 HCP Terraform 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 HCP Terraform 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.