Upgrading from OpenTofu 1.6.x/1.7.x

OpenTofu 1.8.x is mostly compatible with OpenTofu 1.6.x and 1.7.x (other than one minor breaking change in the S3 backend). This migration guide will take you through the process of upgrading OpenTofu to version 1.8.0.

Step 0: Prepare a disaster recovery plan​

Although OpenTofu 1.8 is mostly compatible with version 1.6 and 1.7, you should take the necessary precautions to prevent accidents. Make sure you have an up to date and tested disaster recovery plan.

Step 1: If using an S3 backend - Remove any use of use_legacy_workflow from S3 backend configurations​

If you are using the S3 backend, with use_legacy_workflow set, you'd have to remove it. This field has been deprecated in version 1.7.0, and has been changed to default to false. The legacy workflow of authentication is no longer supported. Please start using the new authentication method, which is more consistent with other AWS tools

Step 2: Apply all changes with OpenTofu 1.6.x/1.7.x​

Before proceeding, make sure that you apply all changes with tofu apply. Running tofu plan should result in no planned changes. While you can switch to OpenTofu with pending changes, it is not recommended.

$ tofu plan

...

No changes. Your infrastructure matches the configuration.

OpenTofu has compared your real infrastructure against your
configuration and found no differences, so no changes are needed.

Step 3: Install OpenTofu 1.8.x​

As a first step, please follow the installation instructions for the OpenTofu CLI tool. Please test if you can successfully execute the tofu command and receive the correct version:

$ tofu --version
OpenTofu v1.8.0
on linux_amd64

Step 4: Back up your state file​

Before you begin using the tofu binary on your Terraform code, make sure to back up your state file. If you are using a local state file, you can simply make a copy of your terraform.tfstate file in your project directory.

If you are using a remote backend such as an S3 bucket, make sure that you follow the backup procedures for the backend and that you exercise the restore procedure at least once.

Step 5: Initialize OpenTofu 1.8.x​

Now you are ready to migrate. Run tofu init in the directory where your code resides. OpenTofu will download any providers and modules referenced in your configuration from the OpenTofu registry.

Step 6: Inspect the plan​

Once initialized, run tofu plan and ensure that there are no pending changes similar to step 1 above. If there are unexpected changes in the plan, roll back to OpenTofu 1.6.x/1.7.x and troubleshoot your migration. (See the Troubleshooting section below.)

$ tofu plan

...

No changes. Your infrastructure matches the configuration.

OpenTofu has compared your real infrastructure against your
configuration and found no differences, so no changes are needed.

Step 7: Test out a small change​

Before you begin using OpenTofu for larger changes, test out tofu apply with a smaller, non-critical change.

Rolling back and reporting issues​

If you have issues migrating to OpenTofu you can follow these steps to roll back to OpenTofu 1.6.x/1.7.x:

1. Create another backup of your state file.
2. Remove OpenTofu 1.8.x and verify that you are running OpenTofu 1.6.x/1.7.x.
3. Run tofu init.
4. Run tofu plan and verify that no unexpected changes are in the plan.
5. Test the rollback with a small, non-critical change.

If you encountered a bug, please report it on GitHub.

Troubleshooting​

If you encounter any issues during the migration to OpenTofu, you can join the OpenTofu Slack or ask on GitHub Discussions.

Error: Failed to query available provider packages​

This error happens when a provider you specified in your configuration is not available in the OpenTofu registry. Please roll back to OpenTofu 1.6.x/1.7.x and make sure your code works with that version. If your code works, please submit an issue to include the provider in the registry.

Error: Module not found​

This error happens when a module you specified in your configuration is not available in the OpenTofu registry. Please roll back to OpenTofu 1.6.x/1.7.x and make sure your code works with that version. If your code works, please submit an issue to include the module in the registry.