Downgrading Terraform Version in the State

Introduction

Once an apply is performed, the version of Terraform that performed the apply is saved in the state file. From that point, the terraform command that performs subsequent operations on the state file must be the same version or a later version. By default, an earlier version of Terraform will not operate on a state file that was created with a later version, because this is not guaranteed to be safe.

Use Case

In some circumstances it may be required to downgrade the Terraform version as recorded in the state file. There are a few options available for performing a downgrade.

If an earlier version of the state file used an earlier version of Terraform, downgrade Terraform to the version specified in that state, and rerun any applies needed.

This is only possible when there is a relatively small difference between states, and downtime wouldn’t be incurred by any necessary resource re-creation or removal.

Procedure

Manually edit the state file and specify a different Terraform version

Manual editing can be used even when there is a large number of changes, but there is no guarantee of a successful operation. Typically, a downgrade will not encounter issues as long as it is between minor versions (e.g., downgrading a state file from 0.11.5 to 0.11.3). Downgrading between major versions is strongly discouraged.

There are two main situations that may be encountered when downgrading the Terraform version in the state file; moving between 0.11.x versions or between 0.12.x and above versions.

Downgrading Terraform version between 0.11.x

There are three steps involved when performing a manual edit of the state file:

1. If you’re running in Terraform Enterprise (TFE), configure Terraform locally with a TFE backend.

2. Back up a copy of the latest state file for safekeeping. From TFE, the following command may be used. For backends other than remote (TFE), manually make a safe copy locally or on another backend.

    $ terraform state pull > latest-state.json

3. Edit the state file, changing the terraform_version value to the desired earlier version.

For example, to downgrade from 0.11.5 to 0.11.3, change:

    "terraform_version": "0.11.5",

to

    "terraform_version": "0.11.3",

Once the change is made and the state file is saved, upload the state file into any backend to make it the latest state (see Modifying Terraform states in Terraform Enterprise for TFE to upload the edited state file to TFE).

Once this operation is complete, downgrade Terraform to the corresponding version (0.11.3 in this example) locally, as well as in Terraform Enterprise. Then run a normal plan operation to ensure that the desired results are produced.

Downgrading Terraform version between 0.12.x and above

The behavior of Terraform CLI has changed since version 0.12.0. Specifically, when pushing the state to the remote backend, Terraform CLI overrides the terraform_version to the current version of Terraform CLI binary that initiates the push operation from the local directory. Because of this, the steps above with Terraform CLI 0.11.x are no longer applicable. In this scenario, HashiCorp Support suggest to follow the guides for Creating a State Version Using the API

Additional information

If you continue to experience the issues after following the guides, please contact HashiCorp Support to request for further assistance.