Migrating from Terraform to OpenTofu step by step.

Migrating from Terraform to OpenTofu step by step is less daunting than it first looks, because OpenTofu began as a fork of Terraform built for compatibility with existing configurations and state. For versions near the fork point, much of the work is changing the binary the pipeline calls and confirming that everything still behaves. The discipline that turns this from a risky cutover into a routine change is sequencing: assess before you touch anything, pilot on something you can afford to break, back up state religiously, cut over in stages, and verify at every step. Done in that order, the migration removes the Business Source License exposure on your provisioning layer without a heroic effort.

This guide walks through the phases in order. For the background on why Terraform moved and what the license means, see HashiCorp BSL: what changed and what it means, and the wider cluster lives on the pillar for HashiCorp and Terraform license risk.

Step one: assess before you move

Start with a clear picture of what you run. Record your Terraform version, the providers and modules in use, the state backends, and the way Terraform is invoked across pipelines and local workflows. The version matters most, because OpenTofu compatibility is strongest near the fork point and narrows as both projects add features independently. If you are on a recent Terraform release that has diverged, expect more verification work. List any features you depend on that may differ between the two tools, and note where state lives, since state is the asset you most need to protect. This assessment is the same inventory discipline that underpins all relicensing work, and it tells you whether the migration is a swap or a project.

The assessment also confirms the case for moving at all. If your use is clearly outside the competitive restriction and you are content to stay on the Business Source License, migration may not be urgent. That judgment is explored in is your Terraform use competitive under the BSL.

Step two: pilot on a low risk workspace

Choose a single, non critical workspace and run OpenTofu against it in parallel before changing anything in production. Install OpenTofu alongside Terraform, point it at a copy of the configuration, and generate a plan. The goal is to confirm that OpenTofu produces the same plan Terraform would, with no unexpected changes, additions, or destructions. A matching plan is the strongest signal that the tools agree on the state of the world. Resolve any differences here, in a setting where a mistake costs nothing, rather than discovering them mid cutover on something that matters.

Use the pilot to validate the providers and modules you flagged in the assessment. Most move cleanly, but the pilot is where you find the exception before it finds you. It also lets the team build confidence with the new tool on something forgiving.

Step three: back up state and cut over in stages

State is the one thing you cannot afford to lose, so back it up before every cutover and keep the backups until you are confident. Then migrate workspace by workspace rather than all at once. For each one, back up the state, switch the tool, generate a plan, confirm it matches expectations, and only then apply. Staging the cutover means that if a workspace behaves unexpectedly, the blast radius is that one workspace and you can roll back to Terraform with the state you preserved. Resist the urge to flip everything in a single change window, however tempting the speed, because a staged migration is the difference between a contained hiccup and a broad outage.

Update the pipeline deliberately as part of each stage. The build tooling that calls the provisioning tool is itself a place license risk hides, which is why the cutover is a good moment to inventory it properly, as covered in license risk in your CI CD and build tooling.

Step four: verify and document

After each workspace is on OpenTofu, verify that day to day operations work: plans, applies, drift detection, and any automation that depends on the tool. Run a full plan to confirm there is no unexpected drift, and check that downstream systems reading state or outputs still function. Finally, document the migration so it is defensible. Record which workspaces moved, when, from which Terraform version to which OpenTofu version, and where the state backups live. That record turns the migration from tribal knowledge into evidence you can show an auditor, and it feeds the wider map of your estate that any relicensing response depends on. The fork itself, and why a community fork is a credible long term path, is told in the OpenTofu and Valkey fork story.

Migrating from Terraform to OpenTofu is a manageable project when it is sequenced rather than rushed. Assess, pilot, back up and stage, then verify and document. The result is an openly licensed provisioning layer with the Business Source License exposure removed and a clean record of how you got there. This article is commercial and licensing risk advisory, not legal advice. For interpretation of a specific license and your compliance position, your own counsel is the right place to turn.