tofu

name	tofu
description	OpenTofu infrastructure-as-code reference for HCL syntax, state management, module design, and provider configuration. Use when working with OpenTofu configurations (.tf files), running tofu commands, troubleshooting state issues, or designing modules. Includes Proxmox provider patterns. Triggers: tofu, opentofu, tfstate, .tf files, HCL, modules, providers.
agent	tofu-expert

OpenTofu Skill

Infrastructure-as-code reference for OpenTofu configurations, state management, and provider patterns.

OpenTofu is the open-source fork of Terraform, maintained by the Linux Foundation. Commands and syntax are nearly identical to Terraform.

Quick Reference

# Core workflow
tofu init              # Initialize, download providers
tofu validate          # Syntax validation
tofu fmt -recursive    # Format HCL files
tofu plan              # Preview changes
tofu apply             # Apply changes

# Inspection
tofu state list                    # List resources in state
tofu state show <resource>         # Show resource details
tofu graph | dot -Tsvg > graph.svg # Dependency graph

# Debug
TF_LOG=DEBUG tofu plan 2>debug.log

Core Workflow

init → validate → fmt → plan → apply

1. init: Download providers, initialize backend
2. validate: Check syntax and configuration validity
3. fmt: Ensure consistent formatting
4. plan: Preview what will change (review carefully)
5. apply: Execute changes

Terraform Migration

OpenTofu is a drop-in replacement for Terraform:

# Replace terraform with tofu in commands
terraform init  →  tofu init
terraform plan  →  tofu plan
terraform apply →  tofu apply

# State files are compatible
# Provider configurations work the same
# Most modules work without changes

Key differences:

• Different binary name (tofu vs terraform)
• Some newer Terraform features may not be available yet
• Provider registry defaults differ (can be configured)

Reference Files

Load on-demand based on task:

Topic	File	When to Load
Troubleshooting	troubleshooting.md	Common errors, debugging
State	state-management.md	Backends, locking, operations
Modules	module-design.md	Module patterns, composition
Security	security.md	Secrets, state security
Migration	migration.md	Terraform → OpenTofu
Proxmox Gotchas	proxmox/gotchas.md	Critical provider issues
Proxmox Auth	proxmox/authentication.md	Provider config, API tokens
Proxmox VMs	proxmox/vm-qemu.md	proxmox_vm_qemu patterns

Validation Checklist

Before tofu apply:

• tofu init completed successfully
• tofu validate passes
• tofu fmt applied
• tofu plan reviewed (check destroy/replace operations)
• Backend configured correctly (for team environments)
• State locking enabled (if remote backend)
• Sensitive variables marked sensitive = true
• Provider versions pinned
• No secrets in version control
• Blast radius assessed (what could break?)

Variable Precedence

(highest to lowest)

1. -var flag: tofu apply -var="name=value"
2. -var-file flag: tofu apply -var-file=prod.tfvars
3. *.auto.tfvars files (alphabetically)
4. terraform.tfvars file
5. TF_VAR_* environment variables
6. Variable defaults in variables.tf

Provider Configuration

# versions.tf
terraform {
  required_version = ">= 1.6.0"  # OpenTofu version

  required_providers {
    proxmox = {
      source  = "Telmate/proxmox"
      version = "~> 3.0"
    }
  }
}