/devops-iac

name: devops-iac
description: Use when writing, reviewing or operating infrastructure as code with OpenTofu or Terraform - choosing between them, project layout, provider pinning and the lock file, remote state (S3-compatible/MinIO, HTTP, PostgreSQL, Kubernetes), locking and state encryption, state surgery (import/moved/removed blocks, state mv/rm, force-unlock), modules, variables and validation, environments (workspaces vs directories vs Terragrunt), the saved-plan review/apply workflow, drift detection, tofu/terraform test, tflint/checkov/trivy, and the providers for Proxmox VE, OpenStack, Kubernetes/Helm, Docker and libvirt. Not for Ansible (devops-ansible), Packer and cloud-init images (devops-virtualization), Proxmox or OpenStack platform internals (devops-proxmox, devops-openstack), secret stores (devops-secrets), CI pipeline authoring (devops-cicd) or public-cloud providers.
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"
user-invocable: true
references:
  - references/tofu-vs-terraform.md
  - references/layout-providers-lock.md
  - references/state-backends-encryption.md
  - references/state-surgery.md
  - references/modules-variables.md
  - references/environments.md
  - references/plan-apply-protocol.md
  - references/testing-quality.md
  - references/provider-proxmox.md
  - references/provider-openstack.md
  - references/provider-k8s-docker-libvirt.md
  - references/templates/root-module.tf
  - references/templates/encryption.tf
  - references/templates/module-skeleton.tf
  - references/templates/proxmox-vm-cloudinit.tf
  - references/templates/openstack-instance-network.tf
  - references/templates/import-moved-removed.tf
  - references/templates/main.tftest.hcl
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

<objective> Covers infrastructure as code with OpenTofu and Terraform for a self-hosted audience (Proxmox, OpenStack, Kubernetes, Docker, libvirt): the tool choice, layout and version pinning, remote state with locking and encryption, safe state surgery, modules, environments, a plan-then-apply protocol that never applies an unreviewed plan, drift detection, tests and static scanning. The main danger is destruction through state; every destructive command is shown with its exact effect. Does not cover Ansible, Packer/cloud-init, platform internals, secret stores, pipeline authoring or public clouds. </objective>

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 `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - find the root modules, backends, providers, lock file, workspaces, wrappers (Makefile, Terragrunt, CI) and which binary (`tofu` or `terraform`) the repo uses 2. **fuse-ai-pilot: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) 3. **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](references/plan-apply-protocol.md)). After file changes, run **fuse-ai-pilot: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

1. **Plan, read, show, then apply that exact plan** - `plan -out=FILE`, read the summary line and every `replace` (`-/+`) and `destroy`, show it to the user, `apply FILE` only after the user's go. Never apply from a dirty tree, a stale plan or an unreviewed plan. 2. **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](references/plan-apply-protocol.md)). 3. **Back up state before any surgery** - `state pull > backup` plus bucket versioning; with encryption on, the key is part of the backup. 4. **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". 5. **Pin everything and commit the lock file** - `required_version`, provider `version`, exact module versions, `.terraform.lock.hcl`. 6. **Secrets never in `.tf`, `.tfvars` committed or state when avoidable** - ephemeral values and write-only arguments first, then encrypted state; the secret store is `devops-secrets`. 7. **Say which binary*