Migrating from Terraform to OpenTofu

Switching from Terraform to OpenTofu is a popular move for organizations and individuals who want to maintain a truly open-source and community-driven Infrastructure as Code (IaC) workflow. The migration process is designed to be straightforward and this guide provides a clear overview to help you make the transition smoothly.

If you are searching for the migration commands, we'll get right into it now. If you want to learn more about the history of the project and the differences between Terraform and OpenTofu, please see the sections below.

How to Migrate

Migrating a simple project from Terraform to OpenTofu is a straightforward process. Let's assume you have a Terraform project that provisions an AWS S3 bucket.

1. Verify Your Current State First, ensure your Terraform state is clean and there are no pending changes.

$ terraform plan
No changes. Your infrastructure matches the configuration.

If there are changes, apply them with terraform apply before proceeding.

2. Backup Your State File This is a critical step. Always back up your terraform.tfstate file and any remote state before a migration.

3. Install OpenTofu Install the OpenTofu CLI on your machine. You can use a package manager like Homebrew on macOS or follow the official installation instructions for your operating system.

$ brew install opentofu
$ tofu --version
OpenTofu v1.6.2

Now, you can use the tofu command as a drop-in replacement for terraform.

4. Initialize OpenTofu Run tofu init upgrade in your project directory. This will download any necessary providers and modules from the OpenTofu registry. The reason for running upgrade is to ensure there are no conflicts with pulling the providers from the OpenTofu registry.

$ tofu init upgrade
Initializing the backend...
Initializing provider plugins...
...

5. Plan and Apply with OpenTofu Run tofu plan to ensure that OpenTofu recognizes your existing infrastructure and configuration without planning any unexpected changes.

$ tofu plan
No changes. Your infrastructure matches the configuration.

Once you are confident, run tofu apply to update the state file to the OpenTofu format. This step is crucial for OpenTofu to take full ownership of the state.

$ tofu apply
No changes. Your infrastructure matches the configuration.
...
Apply complete!

Your project is now successfully migrated to OpenTofu!

Why Migrate from Terraform to OpenTofu?

The primary reason for the migration is a change in the licensing model for Terraform. In 2023, HashiCorp, changed the license for their core products from the open-source Mozilla Public License (MPL) to the more restrictive Business Source License (BSL). This change limits how the software can be used.

OpenTofu was created as a community fork of the last open-source version of Terraform. It's managed by the Linux Foundation, is in the CNCF, and is committed to remaining under a genuinely open-source license (MPL 2.0). This offers a number of key benefits:

• Truly Open Source: Provides long-term assurance against future license changes.
• Community-Driven Development: Features and fixes are prioritized based on the community's needs, not a single company's business interests.
• Impartial Management: Being part of the Linux Foundation ensures that no single vendor can dictate the project's direction.

Version Overview and Code Migration

OpenTofu was forked from Terraform v1.5.7, so its earliest versions are a drop-in replacement for any configuration compatible with that version or earlier. The OpenTofu project aims to maintain backward compatibility with existing Terraform configurations. As OpenTofu and Terraform continue to evolve separately, they may introduce unique features, but the core components will remain the same. For a simple migration, you can expect your existing Terraform code to work with OpenTofu with minimal, if any, changes.

Here's a general guide for version compatibility:

• Migrating from Terraform v1.5.x or lower: You should first migrate to OpenTofu v1.6.x and then upgrade to the latest OpenTofu version. OpenTofu v1.6.2 is fully compatible with Terraform v1.5.x.
• Migrating from Terraform v1.6.x and newer: As mentioned earlier, the core components from Terraform are unchanged so the migration is still striaght forward. That being said, you need to be aware of any new features or syntax introduced in later Terraform versions that may not be supported by OpenTofu.

Key Differences Between the Two Platforms

While the core functionality of both tools remains largely the same, a few key differences have emerged since the fork:

Things to Consider

• Provider Sources: By default, OpenTofu uses registry.opentofu.org. If your configurations explicitly use the old registry.terraform.io source, you may need to update them to use the OpenTofu registry to avoid potential licensing issues and ensure you get the latest OpenTofu-compatible providers.
• Tooling and Integrations: Check for compatibility with any third-party tools you use (e.g., CI/CD pipelines, linters, security scanners). Most tools that work with older versions of Terraform will work fine with OpenTofu, but it's always good to verify.
• Module Compatibility: While most community modules are compatible, confirm that any specific modules you rely on are also compatible with OpenTofu.
• Testing: After a migration, perform small, non-critical changes and test them thoroughly to ensure everything works as expected before making any major updates to your infrastructure.