Migration to OpenTofu¶

Step 1: Upgrading Terraform version¶

This migration guide is only valid for Terraform 1.5.7. If you are on a Terraform version below 1.5.7, please upgrade to at least Terraform version 1.5.7 before proceeding with the migration by following the Terraform upgrade guide. If you are on a higher Terraform version, please select the appropriate migration guide for your Terraform version.

Step 2: Apply all changes with Terraform¶

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

$ terragrunt plan

...

No changes. Your infrastructure matches the configuration.

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

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:

$ tofu --version
OpenTofu v1.6.2
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 GCS bucket, make sure that you have versioning enabled so you can roll back the state file.

Step 5: Initialize OpenTofu¶

Warning¶

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 the community by opening an issue.

Now you are ready to migrate. Remove local terragrunt caches. Set the TERRAGRUNT_TFPATH env variable to "tofu". Then run init in the directory where your Terraform code resides. OpenTofu will download any providers and modules referenced in your configuration from the OpenTofu registry.

### REMOVE LOCAL TERRAGRUNT CACHES FIRST ###

export TERRAGRUNT_TFPATH="tofu"
terragrunt init

...

Step 6: Inspect the plan¶

Once initialized, run plan and ensure that there are no pending changes similar to step 2 above. If there are unexpected changes in the plan, roll back to Terraform and troubleshoot your migration. (See the Troubleshooting section below.)

### MAKE SURE YOU HAVE TERRAGRUNT_TFPATH="tofu" set ###

terragrunt 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: Apply¶

Even though there should be no changes in your infrastructure, you should run apply to ensure that OpenTofu updates the state file.

Step 8: Test out a small change¶

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

Step 9: 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:

1. Create another backup of your state file. 2.

      Run unset TERRAGRUNT_TFPATH
   

2. Run terragrunt init.

3. Run terragrunt plan and verify that no unexpected changes are in the plan.
4. Run terragrunt apply and verify that it runs properly with no changes.
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 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.