Opentofu

---
name: opentofu
description: "Covers OpenTofu, the open-source Terraform fork: HCL, providers, state management, modules, migration from Terraform, feature parity, divergences, and community ecosystem. WHEN: \"OpenTofu\", \"tofu plan\", \"tofu apply\", \"Terraform fork\", \"OpenTofu migration\", \"tofu state\", \"MPL license Terraform\". Do NOT use for Terraform-proper questions with no OpenTofu angle — use the `terraform` skill."
license: MIT
---

# OpenTofu Technology Expert

This skill covers OpenTofu, the open-source fork of Terraform maintained by the Linux Foundation. OpenTofu was created in response to HashiCorp's license change from MPL 2.0 to BSL 1.1 in August 2023. Current version is 1.x.

OpenTofu maintains broad compatibility with Terraform but diverges on newer features. For foundational IaC concepts (state, drift, idempotency), refer to the parent IaC agent.

## How to Approach Tasks

1. **Classify** the request:
   - **Troubleshooting** -- Load `references/diagnostics.md`
   - **Architecture / internals** -- Load `references/architecture.md`
   - **Best practices** -- Load `references/best-practices.md`
   - **Migration from Terraform** -- Cover compatibility, state migration, provider reuse

2. **Identify context** -- Is the user migrating from Terraform, starting fresh, or maintaining an existing OpenTofu setup?

3. **Note divergences** -- OpenTofu and Terraform share a common heritage but diverge on features after the fork point. Always clarify which features are OpenTofu-specific vs shared.

## Core Architecture

OpenTofu shares the same fundamental architecture as Terraform:

- **HCL configuration** -- Same HCL syntax, same `.tf` file format
- **Provider plugin protocol** -- Uses the same gRPC provider protocol (versions 5 and 6). Most Terraform providers work with OpenTofu.
- **State file** -- Same format (version 4). State files are interchangeable between Terraform and OpenTofu.
- **Module system** -- Same module structure, same registry protocol
- **CLI workflow** -- `tofu init`, `tofu plan`, `tofu apply` (drop-in replacement for `terraform` commands)

### Key Differences from Terraform

| Feature | OpenTofu | Terraform |
|---|---|---|
| **License** | MPL 2.0 (open source) | BSL 1.1 (source-available) |
| **Governance** | Linux Foundation, community-driven | HashiCorp (Broadcom) |
| **Registry** | OpenTofu Registry (mirrors + community) | Terraform Registry |
| **State encryption** | Native state encryption (client-side) | No native encryption (rely on backend) |
| **Early variable/locals evaluation** | Supported | Not supported |
| **Provider-defined functions** | Supported (own implementation) | Supported (different implementation) |
| **Removed blocks** | `removed` block for safe resource removal | `removed` block (different syntax) |
| **Stacks** | Not supported | Terraform Cloud/Enterprise only |
| **Cloud integration** | No proprietary cloud service | Terraform Cloud/Enterprise |

### State Encryption

OpenTofu's standout feature — client-side state encryption:

```hcl
terraform {
  encryption {
    key_provider "pbkdf2" "my_passphrase" {
      passphrase = var.state_passphrase
    }

    method "aes_gcm" "my_method" {
      keys = key_provider.pbkdf2.my_passphrase
    }

    state {
      method = method.aes_gcm.my_method
    }

    plan {
      method = method.aes_gcm.my_method
    }
  }
}
```

Key providers: `pbkdf2`, `aws_kms`, `gcp_kms`, `openbao` (Vault fork).

### Early Variable/Locals Evaluation

OpenTofu allows variables and locals in `backend` and `module.source` blocks:

```hcl
# OpenTofu only — not valid in Terraform
variable "environment" {
  type = string
}

terraform {
  backend "s3" {
    bucket = "mycompany-${var.environment}-state"
    key    = "terraform.tfstate"
    region = "us-east-1"
  }
}
```

## Migration from Terraform

### Compatibility Assessment

1. **CLI**: Replace `terraform` with `tofu` — most commands are identical
2. **State**: State files are compatible. No conversion needed.
3. **Providers**: Most providers work. Check the OpenTofu Registry for availability.
4. **Modules**: Terraform Registry modules work if they don't use BSL-only features.
5. **Backend**: Same backend types supported (S3, GCS, Azure Blob, Consul, pg).

### Migration Steps

```bash
# 1. Install OpenTofu
brew install opentofu    # macOS
# or download from https://opentofu.org/docs/intro/install/

# 2. Verify version
tofu version

# 3. Initialize (downloads providers from OpenTofu Registry)
tofu init

# 4. Validate
tofu validate

# 5. Plan (compare against existing state)
tofu plan

# 6. If plan matches expectations, you're migrated
# State file remains in the same backend — no migration needed
```

### Breaking Points

- **Terraform Cloud/Enterprise features**: Remote execution, Sentinel policies, private registry — no OpenTofu equivalent
- **BSL-only features**: Features added to Terraform after 1.5.x may not be in OpenTofu (or may be implemented differently)
- **Provider mirroring**: Some providers may lag in the OpenTofu Registry. Use `provider_installation` block to configure mirrors.

```hcl
# Use Terraform Registry as fallback
provider_installation {
  direct {
    exclude = []
  }
}
```

## CLI Reference

```bash
# Core workflow (identical to Terraform)
tofu init              # Initialize, download providers
tofu plan              # Preview changes
tofu apply             # Apply changes
tofu destroy           # Destroy all resources

# State management
tofu state list
tofu state show <resource>
tofu state mv <source> <dest>
tofu state rm <resource>
tofu import <resource> <id>

# Validation and formatting
tofu validate
tofu fmt -check -recursive
tofu test              # Run tests

# State encryption
tofu init -migrate-state    # Enable encryption on existing state
```

## Reference Files

- `references/architecture.md` — OpenTofu internals, registry architecture, provider compatibility layer, state encryption deep dive, fork divergence tracking
- `references/best-practices.md` — Migration strategies, provider pinning, state encryption configuration, CI/CD integration, community module usage
- `references/diagnostics.md` — Provider compatibility issues, state migration errors, encryption key management, registry resolution failures