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
Note
This tutorial assumes that you are using a tutorial-specific Terraform Cloud organization with a global variable set of your AWS credentials. Review the Create a Credential Variable Set for detailed guidance. If you are using a scoped variable set, assign it to your new workspace now.
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:
- Choose "Version control workflow".
- 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.
- Select the
learn-terraform-versions
repository you forked earlier. - Leave the workspace name as-is
- Expand the Advanced options menu and make sure that Terraform Cloud enabled Automatic speculative plans.
- 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.
Note
In this tutorial scenario, the only compatibility issue is the configuration's version constraint. Production configuration upgrades may require more modification; when updating configurations, consult the Terraform upgrade guides.
Clone your fork of the tutorial repository, replacing USERNAME
with your GitHub username.
Change to the repository directory.
Open main.tf
and update the required_version
constraint to ~> 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.
Stage your changes.
Commit your changes.
Finally, push your changes.
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.
Note
For more information about Terraform 0.13's state changes, review the 0.13 upgrade guide and 0.14 upgrade guide.
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.
Tip
Refer to the Clean Up the Resources and Workspace for detailed guidance on destroying resources in Terraform Cloud.
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.