From Terraform to OpenTofu: A Migration Guide
· via StackGuardian
Why this matters now: The licence change forced a decision on every platform team, and OpenTofu is close to a drop-in replacement from some Terraform versions and a diverging fork from others. The fork keeps the MPL 2.0 licence, and releases 1.7 through 1.9 added native state encryption, variables in backend configuration and provider iteration with for_each. Each release widens the gap, so the cost of waiting grows. Weighing the switch belongs in any serious IaC modernization plan, whichever way you decide.
Three takeaways:
- Match the migration path to your starting version. Document the Terraform and provider versions in every project first. Before Terraform 1.6 the switch is close to a binary swap. From 1.9.x the guide lays out a defined nine-step sequence with specific code changes around backend configuration, and it is reversible: rollback reverts the code, reinitializes with terraform init, and verifies a clean plan.
- Check provider and module compatibility first. Most providers and modules work unchanged, but configurations that reference registry.terraform.io explicitly need updates, and search.opentofu.org confirms what the OpenTofu registry actually mirrors. Update CI/CD to run tofu in place of terraform commands.
- Decide the rollback plan before you migrate, then roll out in stages. Back up state, test the recovery procedure before production, and start with low-risk stacks. Verify the cutover with a small change before trusting it with real work. Fidelity took two quarters to reach 70% of projects. Staying on Terraform remains sensible for teams invested in the wider HashiCorp stack alongside Vault or Consul.
What I’d add today: OpenTofu has been adding innovative features pushing the boundaries such as Native, built-in state encryption, early variable evaluation, provider iteration with for_each, exclude specific resources from operations, OCI registry support
Who should read it: platform teams still on Terraform and weighing a move, especially with a large multi-team estate where a botched cutover is expensive. A migration is also a natural point to tighten the workflow, since the Terraform best practices you already follow carry over to tofu unchanged.