- Getting started
- Migrating to OpenTofu
- Migrating from Terraform 1.6.x
Migrating to OpenTofu from Terraform 1.6.x
When migrating from Terraform 1.6.x, please migrate to OpenTofu 1.6.2 first, then upgrade your OpenTofu installation to the latest version.
OpenTofu 1.6.2 is largely compatible with Terraform 1.6.x with a few minor changes needed. This migration guide will take you through the process of switching from Terraform to OpenTofu.
Step 0: Prepare a disaster recovery plan
Although OpenTofu 1.6.2 is very similar to Terraform 1.6.6, make sure you have an up to date and tested disaster recovery plan.
Step 1: Upgrading Terraform
This migration guide is only valid for Terraform 1.6.6. If you are on a Terraform version below 1.6.6, please upgrade to at least Terraform version 1.6.6 before proceeding with the migration by following the Terraform upgrade guide. If you are on a higher Terraform version, please upgrade to the next minor version of Terraform and use the appropriate migration guide.
Step 2: Apply all changes with Terraform
Before proceeding, make sure that you apply all changes with terraform apply
. Running terraform plan
should result
in no planned changes. While you can switch to OpenTofu with pending changes, it is not recommended.
Step 3: Install OpenTofu 1.6.2
As a first step, please follow the installation instructions for the OpenTofu CLI tool. Make sure
to install OpenTofu 1.6.2. Please test if you can successfully execute the tofu
command and that it returns the
correct version:
Step 4: Back up your state file and code
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.
Additionally, make sure you back up or version your code as the migration will require some code changes.
Step 5: Code changes
For a successful migration, you will need to perform the following code changes
S3 backend
If you are using the S3 backend, please change your code as follows:
- If you are using the
skip_s3_checksum
option on the S3 backend, remove this option as OpenTofu does not need it. - If you are using the
endpoints
→sso
option or theAWS_ENDPOINT_URL
environment variable, remove this option and verify if your code still works as intended after the migration.
Step 6: Initialize OpenTofu
Should any of the following steps fail, please do not proceed and follow the rollback instructions below instead. If you suspect the failure may be the result of a bug in OpenTofu, please help us by opening an issue.
Now you are ready to migrate. Run tofu init
in the directory where your Terraform code resides. OpenTofu will download
any providers and modules referenced in your configuration from the OpenTofu registry.
Step 7: 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 Terraform and troubleshoot your migration. (See the Troubleshooting section
below.)
Step 8: Apply
Even though there should be no changes in your infrastructure, you should run tofu apply
to ensure that OpenTofu
updates the state file.
Step 9: Test out a small change
Before you begin using OpenTofu for larger changes, test out tofu apply
with a smaller, non-critical
change.
Step 10: Upgrade to the latest OpenTofu version
Now that the migration is complete, follow the upgrade guide for OpenTofu to upgrade to the latest version.
Rolling back to Terraform and reporting issues
If you have issues migrating to OpenTofu you can follow these steps to roll back to Terraform:
- Create another backup of your state file and code.
- Remove any code changes you have made.
- Run
terraform init
. - Run
terraform plan
and verify that no unexpected changes are in the plan. - Run
terraform apply
and verify that it runs properly with no changes. - 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 Terraform and make sure your code works with Terraform. 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 Terraform and make sure your code works with Terraform. If your code works, please submit an issue to include the module in the registry.