opentofu-guide

What this skill does

<!--
Progressive Disclosure References:
- references/opentofu-1.10-features.md - OCI registry, native S3 locking, deprecation warnings
- references/opentofu-1.11-features.md - Ephemeral resources, enabled meta-argument
- references/state-encryption.md - Complete state encryption guide with KMS integration
-->

## 🚨 CRITICAL GUIDELINES

### Windows File Path Requirements

**MANDATORY: Always Use Backslashes on Windows for File Paths**

When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).

**Examples:**
- ❌ WRONG: `D:/repos/project/file.tsx`
- ✅ CORRECT: `D:\repos\project\file.tsx`

This applies to:
- Edit tool file_path parameter
- Write tool file_path parameter
- All file operations on Windows systems

### Documentation Guidelines

**NEVER create new documentation files unless explicitly requested by the user.**

- **Priority**: Update existing README.md files rather than creating new documentation
- **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise
- **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone
- **User preference**: Only create additional .md files when user specifically asks for documentation

---


# OpenTofu Expertise and Migration Guide

## Overview

OpenTofu is the open-source fork of Terraform, created in 2023 after HashiCorp changed Terraform's license from MPL 2.0 to BSL (Business Source License). OpenTofu is stewarded by the Linux Foundation and maintains full compatibility with Terraform 1.5.x while adding community-driven features.

## Key Differences (2025)

### Licensing

**Terraform (HashiCorp):**
- BSL (Business Source License) since August 2023
- Restrictions on commercial use for competing products
- IBM acquired HashiCorp in 2024

**OpenTofu:**
- MPL 2.0 (Mozilla Public License)
- True open-source
- Linux Foundation governance
- Community-driven development

### Feature Innovations (2025)

**OpenTofu 1.7 Features:**
- **State Encryption**: Client-side encryption (community requested for 5+ years)
- **Loop-able Import Blocks**: for_each in import blocks
- **Dynamic Provider Functions**: Provider-defined functions support
- **Early Variable Evaluation**: Variables in terraform block

**OpenTofu 1.8 Features (Latest):**
- **OpenTofu-Specific Overrides**: Balance compatibility with innovation
- **Early Variable Evaluation Expanded**: Use variables/locals in module sources
- **Enhanced Provider Support**: Improved provider SDK

**Terraform Advantages:**
- **HCP Terraform**: Cloud platform with Stacks, HYOK, Private VCS Access
- **Enterprise Support**: Direct HashiCorp/IBM support
- **Larger Ecosystem**: More established marketplace
- **Sentinel Policies**: Policy-as-code framework (350+ NIST policies)

### Compatibility

**100% Compatible:**
- HCL syntax (same language)
- Provider ecosystem (same registry access)
- State file format (Terraform 1.5.x)
- Module structure
- CLI commands

**Migration Path:**
- Drop-in replacement for Terraform 1.5.x
- No code changes required
- State files portable (with encryption consideration)

## When to Use OpenTofu vs Terraform

### Choose OpenTofu When:

1. **Open-Source Requirements:**
   - Organization policy requires open-source tools
   - Want vendor neutrality
   - Concerned about future license changes

2. **State Encryption Needed:**
   - Compliance requires client-side encryption
   - Want encryption without HCP Terraform
   - Multi-cloud encryption requirements

3. **Cost Optimization:**
   - Want free state encryption
   - No need for HCP Terraform features
   - Budget constraints on tooling

4. **Community-Driven:**
   - Want to influence roadmap
   - Prefer Linux Foundation governance
   - Value community contributions

### Choose Terraform When:

1. **Enterprise Features Required:**
   - Need HCP Terraform Stacks
   - Require HYOK (Hold Your Own Key)
   - Want Private VCS Access
   - Need Sentinel policy enforcement

2. **Enterprise Support:**
   - Want direct HashiCorp/IBM support
   - Need SLA guarantees
   - Require compliance certifications

3. **Advanced Features:**
   - Ephemeral values (1.10+)
   - Terraform Query (1.14+)
   - Actions blocks (1.14+)
   - Latest provider features first

4. **Established Ecosystem:**
   - Existing HCP Terraform investment
   - Tight integration needs
   - Mature tooling requirements

## Migration from Terraform to OpenTofu

### Step 1: Assess Compatibility

```bash
# Check Terraform version
terraform version
# Must be 1.5.x or compatible

# Check provider versions
terraform providers
# All providers compatible (same registry)
```

### Step 2: Install OpenTofu

**Windows:**
```powershell
# Chocolatey
choco install opentofu

# Scoop
scoop install opentofu

# Manual
# Download from https://github.com/opentofu/opentofu/releases
```

**macOS:**
```bash
# Homebrew
brew install opentofu

# Manual
curl -L https://github.com/opentofu/opentofu/releases/download/v1.8.0/tofu_1.8.0_darwin_amd64.tar.gz | tar xz
sudo mv tofu /usr/local/bin/
```

**Linux:**
```bash
# Snap
snap install opentofu --classic

# Debian/Ubuntu
curl -fsSL https://get.opentofu.org/install-opentofu.sh | sh

# Manual
wget https://github.com/opentofu/opentofu/releases/download/v1.8.0/tofu_1.8.0_linux_amd64.tar.gz
tar -xzf tofu_1.8.0_linux_amd64.tar.gz
sudo mv tofu /usr/local/bin/
```

### Step 3: Test Compatibility

```bash
# Navigate to Terraform directory
cd /path/to/terraform/project

# Initialize with OpenTofu (non-destructive)
tofu init

# Validate configuration
tofu validate

# Generate plan (compare with Terraform plan)
tofu plan
```

### Step 4: Migrate State (Optional)

**If NOT using state encryption:**
```bash
# State is compatible - no migration needed
# Just switch from 'terraform' to 'tofu' commands

# Verify state
tofu show
```

**If ENABLING state encryption:**
```bash
# Configure encryption in .tofu file
cat > .tofu <<EOF
encryption {
  state {
    method = "aes_gcm"
    keys {
      name = "my_key"
      passphrase = env.TOFU_ENCRYPTION_KEY
    }
  }

  plan {
    method = "aes_gcm"
    keys {
      name = "my_key"
      passphrase = env.TOFU_ENCRYPTION_KEY
    }
  }
}
EOF

# Set encryption key
export TOFU_ENCRYPTION_KEY="your-secure-passphrase"

# Migrate state (automatically encrypts)
tofu init -migrate-state
```

### Step 5: Update CI/CD

**GitHub Actions:**
```yaml
# Before (Terraform)
- uses: hashicorp/setup-terraform@v3
  with:
    terraform_version: 1.5.0

# After (OpenTofu)
- uses: opentofu/setup-opentofu@v1
  with:
    tofu_version: 1.8.0

# Or manual install
- name: Install OpenTofu
  run: |
    curl -fsSL https://get.opentofu.org/install-opentofu.sh | sh
    tofu version
```

**Azure DevOps:**
```yaml
# Before
- task: TerraformInstaller@0
  inputs:
    terraformVersion: '1.5.0'

# After
- task: Bash@3
  displayName: 'Install OpenTofu'
  inputs:
    targetType: 'inline'
    script: |
      curl -fsSL https://get.opentofu.org/install-opentofu.sh | sh
      tofu version
```

**GitLab CI:**
```yaml
# Before
image: hashicorp/terraform:1.5.0

# After
image: ghcr.io/opentofu/opentofu:1.8.0
```

## State Encryption (OpenTofu Exclusive)

### Configuration

**Basic Encryption:**
```hcl
# .tofu or terraform.tf
encryption {
  state {
    method = "aes_gcm"
    keys {
      name = "primary_key"
      passphrase = env.TOFU_STATE_ENCRYPTION_KEY
    }
  }
}
```

**Key Rotation:**
```hcl
encryption {
  state {
    method = "aes_gcm"
    keys {
      # New key
      name = "key_v2"
      passphrase = env.TOFU_KEY_V2

      # Old key (for decryption)
      fallback {
        name = "key_v1"
        passphrase = env.TOFU_KEY_V1
      }
    }
  }
}
```

**Cloud KMS Integration:**
```hcl
# AWS KMS
encryption {
  state {
    method = "aws_kms"
    keys {
      name = "aws_key"
      kms_key_id = "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
    }
  }
}

# Azure Key Vault
encryption {
  st