OpenTofu Complete Guide 2026: The Open Source Alternative to Terraform

brew install opentofu

curl --proto '=https' --tlsv1.2 -fsSL https://get.opentofu.org/install-opentofu.sh | sh

tofu version

# main.tf
terraform {
  required_version = ">= 1.8"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}
 
provider "aws" {
  region = var.aws_region
}
 
variable "aws_region" {
  description = "AWS region to deploy to"
  type        = string
  default     = "us-east-1"
}
 
variable "instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t3.micro"
}
 
data "aws_ami" "ubuntu" {
  most_recent = true
  owners      = ["099720109477"] # Canonical
 
  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd/ubuntu-22.04-amd64-server-*"]
  }
}
 
resource "aws_instance" "web" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = var.instance_type
 
  tags = {
    Name        = "opentofu-web-server"
    ManagedBy   = "opentofu"
    Environment = "production"
  }
}
 
output "instance_id" {
  description = "EC2 Instance ID"
  value       = aws_instance.web.id
}
 
output "public_ip" {
  description = "Public IP address"
  value       = aws_instance.web.public_ip
}

tofu init      # download providers
tofu plan      # preview changes
tofu apply     # apply changes

# backend.tf
terraform {
  backend "s3" {
    bucket         = "my-opentofu-state"
    key            = "prod/main/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "opentofu-state-lock"
    encrypt        = true
  }
}

# Create S3 bucket
aws s3api create-bucket \
  --bucket my-opentofu-state \
  --region us-east-1
 
# Enable versioning
aws s3api put-bucket-versioning \
  --bucket my-opentofu-state \
  --versioning-configuration Status=Enabled
 
# Create DynamoDB table for locking
aws dynamodb create-table \
  --table-name opentofu-state-lock \
  --attribute-definitions AttributeName=LockID,AttributeType=S \
  --key-schema AttributeName=LockID,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

tofu init

# encryption.tf
terraform {
  encryption {
    key_provider "aws_kms" "my_key" {
      kms_key_id = "arn:aws:kms:us-east-1:123456789:key/mrk-abc123"
      region     = "us-east-1"
    }
 
    method "aes_gcm" "default_method" {
      keys = key_provider.aws_kms.my_key
    }
 
    state {
      method = method.aes_gcm.default_method
    }
 
    plan {
      method = method.aes_gcm.default_method
    }
  }
}

# 1. Install OpenTofu
brew install opentofu
 
# 2. Navigate to your existing Terraform project
cd my-terraform-project
 
# 3. Initialize with OpenTofu (reads existing .terraform.lock.hcl)
tofu init
 
# 4. Verify state is intact
tofu state list
 
# 5. Run a plan to confirm no unexpected changes
tofu plan

# .github/workflows/opentofu.yml
name: OpenTofu CI/CD
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
env:
  TF_VERSION: "1.8.3"
 
jobs:
  plan:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      pull-requests: write
 
    steps:
    - uses: actions/checkout@v4
 
    - name: Setup OpenTofu
      uses: opentofu/setup-opentofu@v1
      with:
        tofu_version: ${{ env.TF_VERSION }}
 
    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
        aws-region: us-east-1
 
    - name: OpenTofu Init
      run: tofu init
 
    - name: OpenTofu Plan
      id: plan
      run: tofu plan -no-color -out=tfplan
 
    - name: Comment PR with Plan
      if: github.event_name == 'pull_request'
      uses: actions/github-script@v7
      with:
        script: |
          const { execSync } = require('child_process');
          const plan = execSync('tofu show -no-color tfplan').toString();
          github.rest.issues.createComment({
            issue_number: context.issue.number,
            owner: context.repo.owner,
            repo: context.repo.repo,
            body: `## OpenTofu Plan\n\`\`\`\n${plan}\n\`\`\``
          });
 
  apply:
    needs: plan
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    environment: production
 
    steps:
    - uses: actions/checkout@v4
 
    - name: Setup OpenTofu
      uses: opentofu/setup-opentofu@v1
      with:
        tofu_version: ${{ env.TF_VERSION }}
 
    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
        aws-region: us-east-1
 
    - name: OpenTofu Init
      run: tofu init
 
    - name: OpenTofu Apply
      run: tofu apply -auto-approve

# tests/main.tftest.hcl
variables {
  aws_region    = "us-east-1"
  instance_type = "t3.micro"
}
 
run "creates_ec2_instance" {
  command = plan
 
  assert {
    condition     = aws_instance.web.instance_type == "t3.micro"
    error_message = "Expected t3.micro instance type"
  }
 
  assert {
    condition     = aws_instance.web.tags["ManagedBy"] == "opentofu"
    error_message = "ManagedBy tag should be opentofu"
  }
}

tofu test