Infrastructure as Code (OpenTofu / Terraform)
Agent Workflow (MANDATORY)
Before ANY change to .tf, .tofu, .tfvars, .tftest.hcl, terragrunt.hcl or state, spawn in parallel, one spawn_agent call each:
- explore-codebase - find the root modules, backends, providers, lock file, workspaces, wrappers (Makefile, Terragrunt, CI) and which binary (
tofuorterraform) the repo uses - research-expert - re-read the registry page and docs of every provider/resource you will write (versions move; the Proxmox and OpenStack providers are community-maintained)
- mcp__context7__query-docs (
/websites/opentofu,/websites/developer_hashicorp_terraform,/bpg/terraform-provider-proxmox) - confirm each argument before writing it
Read-only commands first (plan-apply-protocol.md). After file changes, run sniper.
Overview
| Area | What matters on 2026-11-10 |
|---|---|
| Tool | OpenTofu (Linux Foundation fork) vs Terraform (Business Source License 1.1, licensor IBM, 1.6.0 and later); same HCL core, diverging features |
| Only OpenTofu | State and plan encryption (1.7), -exclude (1.9), provider for_each (1.9), enabled meta-argument (1.11), dynamic prevent_destroy and destroy = false (1.12) |
| Both | Ephemeral resources and write-only arguments (Terraform 1.11+, OpenTofu 1.11+), import/moved/removed blocks, native S3 locking use_lockfile |
| Only Terraform | Actions and terraform query list resources (1.14), Terraform Policy GA (1.17), -minimal-refresh (1.17) |
| Providers | bpg/proxmox is the maintained Proxmox provider; Telmate/proxmox publishes only release candidates on its 3.x line (last stable 2.9.14); OpenStack provider last released 2025-11-11 |
Critical Rules
- Plan, read, show, then apply that exact plan -
plan -out=FILE, read the summary line and everyreplace(-/+) anddestroy, show it to the user,apply FILEonly after the user's go. Never apply from a dirty tree, a stale plan or an unreviewed plan. - Destruction through state is proposed, never run on your own -
destroy, applying a plan that replaces or destroys,state rm,state push,force-unlock,-target,-replace, deleting a backend bucket/table or a lock: ACTION / EFFECT / PROOF / WAIT-FOR-GO (plan-apply-protocol.md). - Back up state before any surgery -
state pull > backupplus bucket versioning; with encryption on, the key is part of the backup. - Never invent an argument, block or provider - every attribute here comes from the provider docs of the pinned version; the rest is under "Not verified".
- Pin everything and commit the lock file -
required_version, providerversion, exact module versions,.terraform.lock.hcl. - Secrets never in
.tf,.tfvarscommitted or state when avoidable - ephemeral values and write-only arguments first, then encrypted state; the secret store isdevops-secrets. - Say which binary - OpenTofu documents compatibility with state files created by Terraform up to 1.5.x; never switch binaries on a live state without the migration guide and a state backup.
Architecture
infra/
├── live/<env>/<stack>/ # root modules: backend, providers, module calls (one state each)
│ ├── versions.tf backend.tf main.tf variables.tf outputs.tf
│ ├── encryption.tf # OpenTofu only
│ ├── .terraform.lock.hcl # committed
│ └── terraform.tfvars # non-secret values only
├── modules/<name>/ # reusable, versioned, tested (tests/*.tftest.hcl)
└── .tflint.hcl .trivyignore # static checks
Versions
Pinned versions:
opentofu: "1.13.9 (stable line); 1.12.12 also supported"
terraform: "1.17.1; 1.16.7"
terragrunt: "1.2.1"
bpg-proxmox-provider: "0.121.0"
openstack-provider: "3.4.0"
kubernetes-provider: "3.5.0"
helm-provider: "3.3.0"
docker-provider: "4.6.0"
libvirt-provider: "0.9.9"
tflint: "0.66.0"
trivy: "0.76.2"
Reference Guide
Concepts
| Topic | Reference | When to Consult |
|---|---|---|
| Tool choice | tofu-vs-terraform.md | License, governance, feature divergence, migration |
| Layout & providers | layout-providers-lock.md | Project tree, version pinning, lock file, registries |
| State | state-backends-encryption.md | Backend choice, S3/MinIO, http, pg, kubernetes, locking, encryption |
| State surgery | state-surgery.md | import, moved, removed, state mv/rm/push, force-unlock |
| Modules | modules-variables.md | Module design, versioning, variables, validation, outputs, locals |
| Environments | environments.md | Workspaces vs directories vs Terragrunt |
| Plan/apply | plan-apply-protocol.md | Saved plans, destructive catalogue, drift, CI pointer |
| Testing | testing-quality.md | fmt, validate, test, tflint, checkov, trivy |
| Proxmox | provider-proxmox.md | Which provider, auth, VM from template |
| OpenStack | provider-openstack.md | clouds.yaml auth, network + instance |
| K8s/Helm/Docker/libvirt | provider-k8s-docker-libvirt.md | Provider choice, v3 schema changes, pitfalls |
Templates
| Template | When to Use |
|---|---|
| root-module.tf | Root module with pinned providers and an S3-compatible backend |
| encryption.tf | OpenTofu state and plan encryption with migration fallback |
| module-skeleton.tf | Reusable module with validated inputs and outputs |
| proxmox-vm-cloudinit.tf | VM cloned from a cloud-init template (bpg provider) |
| openstack-instance-network.tf | Network, router, security group and instance |
| import-moved-removed.tf | Adopt, rename and forget resources without destroying them |
| main.tftest.hcl | Offline plan-only tests for the module skeleton, including negative validation tests |
Quick Reference
tofu version && tofu providers # binary, versions, provider tree
tofu fmt -check -recursive && tofu init -backend=false && tofu validate # offline checks
tofu init && tofu plan -out=tfplan -detailed-exitcode # exit 0 no diff, 1 error, 2 changes
tofu show tfplan # read it; show the user; wait for the go
tofu apply tfplan # only the reviewed file
Best Practices
DO
- One state per stack and environment; remote backend with locking; bucket versioning on
- Provider and module versions pinned; lock file reviewed in code review
movedblocks for renames,removedwithlifecycle { destroy = false }to forgetprevent_destroyon state-like resources (databases, volumes) and VM templates
DON'T
- Run
applywithout a saved plan outside a throwaway lab; use-targetas a routine tool - Run
state push -forceorforce-unlockwithout proof of the cause - Mix
tofuandterraformon one state; commit.tfstate, plan files or.tfvarswith secrets
Related skills
- devops-proxmox
- devops-openstack
- devops-kubernetes
- devops-gitops-packaging
- devops-docker
- devops-virtualization
- devops-ansible
- devops-cicd
- devops-secrets
- devops-databases
- devops-sre-ops