OpenTofu vs Terraform: Complete Migration Guide for Infrastructure as Code

OpenTofu vs Terraform: Making the Right Infrastructure Decision

OpenTofu Terraform migration has become one of the most discussed topics in the infrastructure-as-code community since HashiCorp changed Terraform’s license from MPL 2.0 to BSL 1.1. Consequently, organizations must decide whether to stay with Terraform, migrate to OpenTofu, or adopt a hybrid approach. This guide provides a thorough comparison and step-by-step migration path for production infrastructure.

OpenTofu is a fork of Terraform maintained by the Linux Foundation, ensuring it remains truly open source under the MPL 2.0 license. Moreover, OpenTofu maintains full backward compatibility with Terraform configurations, state files, and providers. Therefore, migration is straightforward for most organizations, but understanding the differences and planning properly is essential for a smooth transition.

OpenTofu Terraform Migration: Feature Comparison

Both tools share the same core HCL syntax and provider ecosystem, but they’ve started diverging in key areas. OpenTofu has introduced several features not available in Terraform, including client-side state encryption and improved testing capabilities. Furthermore, OpenTofu’s governance model ensures community-driven development, while Terraform’s direction is determined by HashiCorp’s commercial interests.

# OpenTofu exclusive: Client-side state encryption
terraform {
  encryption {
    method "aes_gcm" "default" {
      keys = key_provider.aws_kms.main
    }
    state {
      method   = method.aes_gcm.default
      enforced = true
    }
    plan {
      method   = method.aes_gcm.default
      enforced = true
    }
  }

  backend "s3" {
    bucket         = "my-tofu-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "tofu-locks"
    encrypt        = true
  }
}

# Provider configuration remains identical
provider "aws" {
  region = "us-east-1"
  default_tags {
    tags = {
      ManagedBy   = "OpenTofu"
      Environment = "production"
    }
  }
}

Step-by-Step Migration from Terraform to OpenTofu

The migration process is designed to be non-disruptive. Since OpenTofu reads Terraform state files directly, you can migrate incrementally — one project at a time. Additionally, both tools can coexist in the same CI/CD pipeline during the transition period. This approach minimizes risk and allows teams to validate each migration step.

# Step 1: Install OpenTofu
curl --proto '=https' --tlsv1.2 -fsSL \
  https://get.opentofu.org/install-opentofu.sh | sh

# Step 2: Verify compatibility with existing state
cd /path/to/terraform-project
tofu init    # Downloads providers, reads existing state
tofu plan    # Should show no changes (identical state)

# Step 3: Update CI/CD pipeline (GitHub Actions example)
# Replace hashicorp/setup-terraform with opentofu/setup-opentofu

# Step 4: Lock file migration
tofu providers lock \
  -platform=linux_amd64 \
  -platform=darwin_amd64 \
  -platform=darwin_arm64

# Step 5: Validate all modules
tofu validate
tofu fmt -check -recursive

State Management and Backend Compatibility

OpenTofu supports all Terraform backends including S3, Azure Blob Storage, Google Cloud Storage, and Consul. State file format is identical, meaning you can switch between tools without state migration. However, OpenTofu adds client-side encryption that Terraform doesn’t support, giving you an additional layer of security for sensitive state data.

# Module structure remains identical
module "vpc" {
  source  = "registry.opentofu.org/terraform-aws-modules/vpc/aws"
  version = "5.5.0"

  name = "production-vpc"
  cidr = "10.0.0.0/16"

  azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]

  enable_nat_gateway     = true
  single_nat_gateway     = false
  one_nat_gateway_per_az = true

  tags = {
    Terraform   = "false"
    OpenTofu    = "true"
    Environment = "production"
  }
}

# OpenTofu registry is compatible with Terraform registry
module "eks" {
  source  = "registry.opentofu.org/terraform-aws-modules/eks/aws"
  version = "20.8.0"

  cluster_name    = "prod-cluster"
  cluster_version = "1.29"

  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnets

  eks_managed_node_groups = {
    general = {
      instance_types = ["m6i.xlarge"]
      min_size       = 3
      max_size       = 10
      desired_size   = 5
    }
  }
}

CI/CD Pipeline Updates for OpenTofu

Updating your CI/CD pipeline is straightforward since the CLI commands are nearly identical. Replace terraform with tofu in your pipeline scripts. Furthermore, OpenTofu provides official GitHub Actions, GitLab CI templates, and Jenkins plugins for seamless integration. As a result, most teams complete their CI/CD migration within a single sprint.

# GitHub Actions workflow for OpenTofu
name: Infrastructure Deploy
on:
  push:
    branches: [main]
    paths: ['infra/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: opentofu/setup-opentofu@v1
        with:
          tofu_version: 1.7.0

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/tofu-deploy
          aws-region: us-east-1

      - name: Init
        run: tofu init -backend-config=prod.hcl
        working-directory: infra/

      - name: Plan
        run: tofu plan -out=plan.tfplan
        working-directory: infra/

      - name: Apply
        if: github.ref == 'refs/heads/main'
        run: tofu apply plan.tfplan
        working-directory: infra/

When NOT to Migrate

While OpenTofu is excellent for most use cases, some scenarios favor staying with Terraform. If you heavily use Terraform Cloud or Terraform Enterprise features like Sentinel policies, cost estimation, or private registry, the migration effort is higher. Additionally, organizations with HashiCorp Enterprise agreements should evaluate contract terms before switching. See the OpenTofu documentation for detailed compatibility information.

Key Takeaways

• Start with a solid foundation and build incrementally based on your requirements
• Test thoroughly in staging before deploying to production environments
• Monitor performance metrics and iterate based on real-world data
• Follow security best practices and keep dependencies up to date
• Document architectural decisions for future team members

In summary, OpenTofu Terraform migration is a low-risk, high-reward investment for organizations committed to open-source infrastructure management. The identical state format, compatible provider ecosystem, and straightforward CLI migration make the transition smooth. Start with non-production environments, validate your workflows, and gradually roll out to production.