Introduction
There are some scenarios where it may be necessary to downgrade the version of the Terraform command line tool used by Terraform Cloud or Terraform Enterprise (TFC/E).
In workspaces that have already applied on a higher version of Terraform, the state will not allow using a lower version of Terraform. Manual steps must be taken in order to use a lower version of Terraform.
Expected Outcome
A remote state compatible with the desired Terraform version.
Prerequisites
Terraform version between 0.14.x and 1.0.x only.
Use Case
Reasons for downgrading the Terraform version include:
- Provider version incompatibility with Terraform version
- Inadvertently upgraded Terraform version
Procedure
- Follow the steps at Using the remote backend and Terraform CLI to run plan and state operations locally. For step #7 in that guide, instead modify the Terraform Version setting to match the version you are downgrading to. At your local CLI, make sure that your Terraform version matches the desired downgraded version as well. All Terraform CLI releases can be found here.
- In the target Workspace in TFC/E, navigate to the "States" tab, select the latest state record, and download the state file to the local directory containing your Terraform configuration.
- Open the state file in a text editor and increment the `serial` value by 1, e.g. a `git diff` on the file might show:
{
"version": 4,
"terraform_version": "1.0.2",
- "serial": 3,
+ "serial": 4,
... - Run the
terraform state push
command with the-ignore_remote_version
option targeting the just-modified state file to upload to the target Workspace. If the file name issv-zzz.tfstate
, this command would look liketerraform state push -ignore_remote_version ./sv-zzz.tfstate
.
Additional Information
-
This guide only covers through 1.0.x of Terraform because the
cloud
block introduced in Terraform 1.1.0 supersedes the behavior of the remote backend referenced in this guide, and because the V1 Compatibility Promise should allow downgrading from a later v1.x release to an earlier v1.x release, provided no newer language features are being used from the later release.