tofu init, and verify the plan is empty before you apply anything. The only parts that need real work are the registry address, state encryption, and any terraform_remote_state links between configurations.What changed in August 2023 — and what did not
In August 2023 HashiCorp changed the license on its core products, including Terraform, to the Business Source License (BSL) — not an open-source license, since it lets the vendor reserve the right to compete with you and change the terms later. Two weeks later, on August 25, 2023, the OpenTofu project announced a fork of Terraform. The manifesto behind it drew pledges from more than 100 companies, 10 projects, and 400 individuals, and its repository passed 4,000 GitHub stars within days. The project joined the Linux Foundation, aiming for the Cloud Native Computing Foundation, so a foundation — not a vendor — holds the governance.
What did not change is the code you already run. OpenTofu is a fork of Terraform, a drop-in replacement for Terraform 1.5, with documented migration paths from later versions. Your .tf files, modules, providers, and state file all carry over. The migration is a binary swap plus a state handover, and the risk is concentrated in three places: the state file, the registry address, and the links between configurations.
The cost of staying is not a fee — Terraform remains free to use under the BSL. It is a license risk: the terms are set by a vendor that has already changed them once, and the registry, the providers, and the roadmap all answer to that vendor. The migration buys you out of that risk for an afternoon's engineering.
The state file: the one object that matters
OpenTofu must store state about your managed infrastructure: it maps real-world resources to your configuration, tracks metadata, and speeds up large infrastructures. By default it lives in a local file named terraform.tfstate, in JSON format. Before any operation, OpenTofu refreshes the state against the real infrastructure, then computes the difference between the state and your configuration. That difference is the plan.
Three properties of the state file drive the whole migration. First, the state is the binding, not the configuration: your .tf files declare intent, but the state records which remote object — which AWS instance ID, which DNS record, which VPC — answers to each resource block. Lose the state, and OpenTofu cannot tell your production database from a stranger's; it will try to create a second one. Second, the mapping is one-to-one. The tofu state commands repair it when it breaks — tofu import binds an externally created object to a block, and tofu state rm forgets a binding, after which you must delete the orphaned object or re-import it under another block. Third, direct editing is discouraged: the format is JSON, but the project warns against editing it by hand, and guarantees the CLI keeps working even as the format shifts. For anything outside the CLI, tofu show -json and tofu output -json produce machine-readable representations intended for external software.
Because the state is the binding, the migration's first rule is absolute: back up the state before you touch anything, and never let two tools write the same state. A migration that loses the state is a rebuild of production from memory.
The decision: stay, migrate, or run both
| Option | What you pay | What you keep | What you lose | Authority |
|---|---|---|---|---|
| Stay on Terraform | $0 in license fees; the license risk stays with HashiCorp | The Terraform Registry, HashiCorp support, newest features on day one | License certainty; the BSL already changed once | HashiCorp BSL announcement, Aug 2023 |
| Migrate to OpenTofu | One afternoon of engineering per configuration (priced below) | The same code, the same state, an MPL-2.0 license held by a foundation | Day-one access to HashiCorp-only features; some provider versions lag | Fork announcement, Aug 25, 2023; 1.7.0 release notes, Apr 30, 2024 |
| Run both side by side | The migration cost plus dual-tool overhead | A rollback path that stays warm | Two binaries must never write one state file | OpenTofu migration guide: back up state and code first |
The decision turns on how much of your business runs on infrastructure-as-code. If Terraform provisions a staging box, stay. If it provisions the VPC, the database, the DNS, and the CI runners your revenue depends on, the afternoon is cheap insurance. The rest of this guide assumes you migrate — one configuration at a time, starting with the least dangerous one.
tofu apply followed by a terraform apply against one state will produce a plan that recreates resources the other tool just created, because the state lock and the version markers do not coordinate across binaries. Pick one binary per configuration, and lock the other one out of the pipeline until the migration is verified.The migration sequence
The migration guide describes the process as safe and reversible, and it is — if you follow the order.
- Back up the state and the code. Copy the state out of the backend to a location the migration cannot touch — an S3 object to a versioned bucket with a dated key, or
terraform.tfstateandterraform.tfstate.backupto a dated directory. Commit the code, tag it, and record the Terraform version that produced the current state. - Install
tofualongsideterraform, not over it. Pin migration commands to the full path or a wrapper script until the cutover is done. - Point the configuration at the OpenTofu Registry. Terraform resolves providers from
registry.terraform.io; OpenTofu resolves fromsearch.opentofu.org. Pin the provider versions before you migrate. - Run
tofu init. Initialization downloads the providers and writes the lock file. If a provider version is missing from the OpenTofu Registry, this is where you find out — before anything has been applied. - Run
tofu planand demand an empty plan. A correct migration produces zero changes. Any proposed change is a defect — usually a provider version difference or a state address the new binary reads differently. - Apply a small, reversible change. Change a tag or a description with
tofu apply, and confirm that resource changed and nothing else did. This first write proves the backend, the lock, and the credentials all work under OpenTofu. - Cut the pipeline over. Update the CI configuration — GitHub Actions, GitLab CI, Atlantis — to call
tofuinstead ofterraform, and remove the Terraform binary from the runner image or the PATH.
- [x] State backed up outside the backend, versioned and dated
- [x] Code committed and tagged with the Terraform version recorded
- [x] Provider versions pinned and present in the OpenTofu Registry
- [x]
tofu planempty before any apply - [x] Small change applied and verified as the only change
- [x] CI cut over and the Terraform binary removed
The interdependency trap: terraform_remote_state
The one case the migration guide singles out for extra care is configurations that share data through the terraform_remote_state data source. If configuration B reads outputs from configuration A's state, the two migrations are coupled: B's data source must keep resolving while A moves, and the backend addresses in both configurations must agree after the move.
Migrate A first, verify it, then migrate B. Between the two, B reads A's state through the backend — an S3 bucket, an HTTP endpoint, a Terraform Cloud workspace — and that read does not care which binary wrote the state, as long as the backend address and the format are unchanged. The format is the same JSON, so the read works. What breaks is the case where B's state backend is itself a Terraform-managed resource that A provisions. In that case, migrate the backend's configuration last, and keep a local copy of B's state until both are verified.
State encryption: the feature that justifies the move on its own
OpenTofu 1.7.0, released April 30, 2024, shipped end-to-end state encryption — state and plan files encrypted at rest, for local storage and for backends, including use with the terraform_remote_state data source. Terraform under the BSL has no equivalent built-in state encryption. For any operator whose state file contains access keys, database passwords, or private keys — and most contain at least one — this is the strongest technical reason to migrate, independent of the license question.
The encryption model is explicit about its limits. It encrypts state data at rest: an attacker who gains access to the state file cannot read the sensitive values inside it. It does not protect against data loss — a damaged state file is still damaged — or against a replay attack, where an attacker substitutes an older state or plan file. And it cannot protect sensitive values from the person running the tofu command, because that person holds the key.
The key choices are a static passphrase, supplied through environment variables, or a key management system: AWS KMS, GCP Cloud KMS, Azure Key Vault, or OpenBao. Two warnings carry. First, if you use a KMS, configure automatic key rotation for methods that can reach key saturation — AES-GCM has a maximum safe usage limit per key — and use a separate key for each state file. Second, once encryption is enabled, the state file is unrecoverable without the key. Exercise the disaster-recovery plan and make a temporary backup of the unencrypted state before enabling encryption, and keep backups of the keys. An operator who enables encryption, loses the key, and has no unencrypted backup has destroyed their own infrastructure mapping.
What the registry split actually costs
The OpenTofu Registry lives at search.opentofu.org, a separate service from the Terraform Registry. In practice the namespaces overlap heavily — the same hashicorp/aws provider, the same version numbers — because the providers are mostly open-source projects published to both. The cost of the split is lag: a new provider version may reach the Terraform Registry hours or days before the OpenTofu Registry, and a provider published only there is invisible to OpenTofu until its maintainer publishes it to both.
The operational answer is pinning. Pin every provider version, record the versions in the lock file, and check the lock file into version control. A pinned configuration migrates deterministically: tofu init either finds the exact provider versions or fails loudly before anything is applied. An unpinned configuration migrates by luck. The same discipline applies to modules: pin module sources to a version or a commit, because a floating module reference is a second registry dependency you did not know you had.
The cost math: pricing the afternoon
The migration is not free, and the honest way to decide it is to price it against the risk it removes. The cost is engineer time, in three parts.
The rollback reserve is the cost of keeping the Terraform binary and the pre-migration state backup available until the migration is verified. Take a team with 40 state files across 12 configurations, two engineers, and a loaded rate of $85 an hour:
| Cost element | Hours | Calculation | Cost |
|---|---|---|---|
| Migration work | 32 | 2 engineers × 16 hours × $85 | $2,720 |
| Validation | 8 | 8 hours × $85 | $680 |
| Rollback reserve | 4 | 4 hours × $85 | $340 |
| Total | 44 | $3,740 |
The work is one-off, so the cost scales with the number of configurations, not the size of the infrastructure. And because the migration is reversible — the backed-up state and the Terraform binary restore the old position exactly — the downside of a failed migration is the hours spent, not the infrastructure. A bounded, reversible $3,740 buys out an unbounded license risk on the tool that provisions everything the business runs on.
tofu plan runs against production.Founder & CEO Insight — Enow A. Jovial
The operator's sequence, in one place
A migration is done when the new binary has produced the same plan, applied the same change, and survived a full release cycle without a Terraform binary anywhere in the path.
- [x] Inventory every configuration, its state backend, and its provider versions
- [x] Back up every state file to a versioned, dated location
- [x] Install
tofualongsideterraform; pin provider versions - [x] Migrate the cheapest configuration first; demand an empty plan
- [x] Apply one small change; verify it is the only change
- [x] Enable state encryption with a KMS key per state file
- [x] Cut over CI to
tofu; remove the Terraform binary - [x] Archive the pre-migration state backup for one quarter
The Terraform vs Pulumi vs AWS CDK pricing guide prices the three tools against each other; this playbook is the operation that moves you from the first of them to its open fork. The Nomad vs Kubernetes vs Docker Swarm guide covers what runs on the infrastructure once provisioned, and the managed Kubernetes pricing guide prices the clusters OpenTofu provisions. For the cost side, run the numbers through the ROI calculator with the $3,740 figure above as the investment.

