Terraform to OpenTofu Blueprint

What and Why

OpenTofu is an open-source fork of Terraform, created after HashiCorp relicensed Terraform under the Business Source License (BSL). It is governed by the Linux Foundation and aims for drop-in compatibility with Terraform's configuration language, state format, and provider protocol. Organizations migrate to OpenTofu to stay on a permissive open-source license, avoid BSL restrictions on competing or commercial use, and benefit from community-driven features and a vendor-neutral registry.

Because OpenTofu forked from a specific Terraform version, the migration is usually low-risk for projects on compatible versions: the state format and HCL are compatible, so most projects can switch the binary and continue. The care is in version skew, provider source addresses, and any Terraform-only features introduced after the fork point.

Phases

Assessment. Record the current Terraform version and feature usage across all projects. OpenTofu tracks compatibility up to a known Terraform line; flag any use of Terraform features introduced after the fork point, or provider/module features that differ. Inventory providers, modules, the state backend, and any wrappers (Terragrunt, Atlantis, CI scripts). Check provider availability in the OpenTofu Registry, since source addresses use a different namespace.

Pilot. Pick a low-risk, non-production project. Install OpenTofu, point it at the existing state backend (unchanged), and run tofu init then tofu plan. Because the state format is compatible, a clean plan with no proposed changes is the success signal. Resolve any provider source address differences in required_providers, and confirm tofu validate passes.

Migration. Convert projects in waves. Update CI/CD to call tofu instead of terraform, pin the OpenTofu version in CI images and .tool-versions/tfenv-style managers, and update wrappers (Terragrunt, Atlantis) to OpenTofu-aware versions. Keep state backends unchanged so no state migration is needed. Communicate the registry namespace change to contributors.

Cutover. Switch the default tool for each project to OpenTofu, update documentation, pre-commit hooks, and developer tooling, and remove Terraform from CI images. Decommission any Terraform-specific licensing or distribution.

Validation. Run drift detection and a full tofu plan across all environments to confirm parity with no unexpected diffs. Verify that state locking, workspaces, remote state, and policy checks operate identically, and confirm an apply on a trivial change works end to end.

Key Risks and Mitigations

• Provider compatibility. Provider source addresses differ between the two registries. Pin required_providers explicitly with the correct source, and test plans before any apply.
• State drift. State is compatible, but always run a no-op plan before any apply post-switch, keep state bucket versioning enabled, and back up state before the first apply.
• CI breakage. Wrappers and pipelines hard-code the terraform binary and version. Update CI images, pin tool versions, update wrappers, and run the full pipeline on the pilot before broad rollout.

Recommended Tooling

OpenTofu CLI, the OpenTofu Registry, a locking remote backend (unchanged from Terraform), version pinning in CI and via a version manager, and OpenTofu-compatible wrappers (Terragrunt, Atlantis) where used. Vault or a cloud secrets manager for credentials, and policy-as-code that supports OpenTofu plans.

Success Metrics

Track provisioning lead time (should be unchanged), drift incidents, pipeline success rate after the switch, and the percentage of projects fully on OpenTofu.

Prerequisites

Projects on a Terraform version within OpenTofu's compatibility range, a remote state backend, pinned providers, and CI/CD that can be updated to the new binary and version. Confirm that any commercial modules, providers, or policy tooling in use support OpenTofu, and that the team has agreed on how to handle features that diverge between the two tools over time. Take a state backup before the first apply on each project, and communicate the change to all contributors so local developer setups (version managers, editor integrations, pre-commit hooks) are updated in step with CI to avoid mixed-binary confusion.