OpenTofu Migrator

OpenTofu Migrator helps you move existing Terraform configurations to OpenTofu and then take advantage of the features that only exist in the fork. It covers the in-place migration path, client-side state encryption, and OpenTofu-specific HCL constructs that the upstream Terraform CLI rejects. It is aimed at platform and DevOps engineers who already run terraform in CI and want a low-risk switch without rewriting modules.

When to use it

• You want to swap terraform for tofu in CI/CD and need the state, provider lockfile, and .tf files to keep working untouched.
• You need state encrypted at rest with a key you control, not just relying on backend bucket encryption.
• You want OpenTofu-only language features such as variables/locals evaluated early enough to parameterize a backend block or a module source.
• You are writing provider-defined functions and want them resolved by tofu.

How it works

Migration is intentionally boring: tofu init reads your existing .terraform.lock.hcl and remote state as-is, so a project usually moves over by replacing the binary. The skill helps with the CI swap (changing terraform invocations to tofu), checking provider compatibility in the lockfile, and the tofu plan/tofu apply sanity loop after switching.

For encryption it authors an encryption block under terraform {}, wiring a key_provider (pbkdf2 with a passphrase, aws_kms, or gcp_kms) to a method "aes_gcm" and attaching it to state and plan. It supports the unencrypted fallback used during rollout and key rotation via a second method.

It also authors tofu-only constructs: early variable evaluation in backend and module source, and provider:: namespaced function calls.

Usage

curl -fsSL --create-dirs -o ~/.claude/skills/opentofu-iac/SKILL.md https://claudeskil.com/skills/opentofu-iac/SKILL.md

tofu init      # reuses .terraform.lock.hcl + existing state
tofu plan      # expect a no-op diff right after migrating

terraform {
  encryption {
    key_provider "pbkdf2" "k" {
      passphrase = var.state_passphrase
    }
    method "aes_gcm" "m" {
      keys = key_provider.pbkdf2.k
    }
    state { method = method.aes_gcm.m }
    plan  { method = method.aes_gcm.m }
  }
}

Tips & gotchas

• Set TF_ENCRYPTION (or the encryption block) consistently across every machine and CI runner — once state is encrypted, a runner without the key cannot read it.
• To roll encryption out gradually, add an unencrypted {} fallback so tofu can read old plaintext state, then remove it after the first encrypted apply.
• The PBKDF2 passphrase must be at least 16 characters; shorter ones fail at init.
• Encrypted state is opaque to tools that parse terraform.tfstate directly — decrypt via tofu first.

FAQ

Can I migrate back to Terraform later? Only if you avoided tofu-only features and left state unencrypted; encrypted state and provider:: functions are not readable by the Terraform CLI.

Does my provider lockfile still work? Yes — tofu init consumes the existing .terraform.lock.hcl and matching provider hashes.

Is key rotation supported? Yes, by defining a second method and listing both keys so old state decrypts while new writes use the new key.