1---2name: devops-iac3description: 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.4versions:5 opentofu: "1.13.9 (stable line); 1.12.12 also supported"6 terraform: "1.17.1; 1.16.7"7 terragrunt: "1.2.1"8 bpg-proxmox-provider: "0.121.0"9 openstack-provider: "3.4.0"10 kubernetes-provider: "3.5.0"11 helm-provider: "3.3.0"12 docker-provider: "4.6.0"13 libvirt-provider: "0.9.9"14 tflint: "0.66.0"15 trivy: "0.76.2"16user-invocable: true17references:18 - references/tofu-vs-terraform.md19 - references/layout-providers-lock.md20 - references/state-backends-encryption.md21 - references/state-surgery.md22 - references/modules-variables.md23 - references/environments.md24 - references/plan-apply-protocol.md25 - references/testing-quality.md26 - references/provider-proxmox.md27 - references/provider-openstack.md28 - references/provider-k8s-docker-libvirt.md29 - references/templates/root-module.tf30 - references/templates/encryption.tf31 - references/templates/module-skeleton.tf32 - references/templates/proxmox-vm-cloudinit.tf33 - references/templates/openstack-instance-network.tf34 - references/templates/import-moved-removed.tf35 - references/templates/main.tftest.hcl36related-skills:37 - devops-proxmox38 - devops-openstack39 - devops-kubernetes40 - devops-gitops-packaging41 - devops-docker42 - devops-virtualization43 - devops-ansible44 - devops-cicd45 - devops-secrets46 - devops-databases47 - devops-sre-ops48metadata:49 source: https://skillmd.com/skills/fusengine/devops-iac50---5152<objective>53Covers infrastructure as code with OpenTofu and Terraform for a self-hosted54audience (Proxmox, OpenStack, Kubernetes, Docker, libvirt): the tool choice,55layout and version pinning, remote state with locking and encryption, safe state56surgery, modules, environments, a plan-then-apply protocol that never applies an57unreviewed plan, drift detection, tests and static scanning. The main danger is58destruction through state; every destructive command is shown with its exact59effect. Does not cover Ansible, Packer/cloud-init, platform internals, secret60stores, pipeline authoring or public clouds.61</objective>6263# Infrastructure as Code (OpenTofu / Terraform)6465## Agent Workflow (MANDATORY)6667Before ANY change to `.tf`, `.tofu`, `.tfvars`, `.tftest.hcl`, `terragrunt.hcl` or state, spawn in parallel, one `Agent` call each with a `name`:68691. **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 uses702. **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)713. **mcp__context7__query-docs** (`/websites/opentofu`, `/websites/developer_hashicorp_terraform`, `/bpg/terraform-provider-proxmox`) - confirm each argument before writing it7273Read-only commands first ([plan-apply-protocol.md](references/plan-apply-protocol.md)). After file changes, run **fuse-ai-pilot:sniper**.7475---7677## Overview7879| Area | What matters on 2026-11-10 |80|------|----------------------------|81| **Tool** | OpenTofu (Linux Foundation fork) vs Terraform (Business Source License 1.1, licensor IBM, 1.6.0 and later); same HCL core, diverging features |82| **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) |83| **Both** | Ephemeral resources and write-only arguments (Terraform 1.11+, OpenTofu 1.11+), `import`/`moved`/`removed` blocks, native S3 locking `use_lockfile` |84| **Only Terraform** | Actions and `terraform query` list resources (1.14), Terraform Policy GA (1.17), `-minimal-refresh` (1.17) |85| **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 |8687---8889## Critical Rules90911. **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.922. **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)).933. **Back up state before any surgery** - `state pull > backup` plus bucket versioning; with encryption on, the key is part of the backup.944. **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".955. **Pin everything and commit the lock file** - `required_version`, provider `version`, exact module versions, `.terraform.lock.hcl`.966. **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`.977. **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.9899---100101## Architecture102103```104infra/105├── live/<env>/<stack>/ # root modules: backend, providers, module calls (one state each)106│ ├── versions.tf backend.tf main.tf variables.tf outputs.tf107│ ├── encryption.tf # OpenTofu only108│ ├── .terraform.lock.hcl # committed109│ └── terraform.tfvars # non-secret values only110├── modules/<name>/ # reusable, versioned, tested (tests/*.tftest.hcl)111└── .tflint.hcl .trivyignore # static checks112```113114---115116## Reference Guide117118### Concepts119120| Topic | Reference | When to Consult |121|-------|-----------|-----------------|122| **Tool choice** | [tofu-vs-terraform.md](references/tofu-vs-terraform.md) | License, governance, feature divergence, migration |123| **Layout & providers** | [layout-providers-lock.md](references/layout-providers-lock.md) | Project tree, version pinning, lock file, registries |124| **State** | [state-backends-encryption.md](references/state-backends-encryption.md) | Backend choice, S3/MinIO, http, pg, kubernetes, locking, encryption |125| **State surgery** | [state-surgery.md](references/state-surgery.md) | import, moved, removed, state mv/rm/push, force-unlock |126| **Modules** | [modules-variables.md](references/modules-variables.md) | Module design, versioning, variables, validation, outputs, locals |127| **Environments** | [environments.md](references/environments.md) | Workspaces vs directories vs Terragrunt |128| **Plan/apply** | [plan-apply-protocol.md](references/plan-apply-protocol.md) | Saved plans, destructive catalogue, drift, CI pointer |129| **Testing** | [testing-quality.md](references/testing-quality.md) | fmt, validate, test, tflint, checkov, trivy |130| **Proxmox** | [provider-proxmox.md](references/provider-proxmox.md) | Which provider, auth, VM from template |131| **OpenStack** | [provider-openstack.md](references/provider-openstack.md) | clouds.yaml auth, network + instance |132| **K8s/Helm/Docker/libvirt** | [provider-k8s-docker-libvirt.md](references/provider-k8s-docker-libvirt.md) | Provider choice, v3 schema changes, pitfalls |133134### Templates135136| Template | When to Use |137|----------|-------------|138| [root-module.tf](references/templates/root-module.tf) | Root module with pinned providers and an S3-compatible backend |139| [encryption.tf](references/templates/encryption.tf) | OpenTofu state and plan encryption with migration fallback |140| [module-skeleton.tf](references/templates/module-skeleton.tf) | Reusable module with validated inputs and outputs |141| [proxmox-vm-cloudinit.tf](references/templates/proxmox-vm-cloudinit.tf) | VM cloned from a cloud-init template (bpg provider) |142| [openstack-instance-network.tf](references/templates/openstack-instance-network.tf) | Network, router, security group and instance |143| [import-moved-removed.tf](references/templates/import-moved-removed.tf) | Adopt, rename and forget resources without destroying them |144| [main.tftest.hcl](references/templates/main.tftest.hcl) | Offline plan-only tests for the module skeleton, including negative validation tests |145146---147148## Quick Reference149150```bash151tofu version && tofu providers # binary, versions, provider tree152tofu fmt -check -recursive && tofu init -backend=false && tofu validate # offline checks153tofu init && tofu plan -out=tfplan -detailed-exitcode # exit 0 no diff, 1 error, 2 changes154tofu show tfplan # read it; show the user; wait for the go155tofu apply tfplan # only the reviewed file156```157158---159160## Best Practices161162### DO163- One state per stack and environment; remote backend with locking; bucket versioning on164- Provider and module versions pinned; lock file reviewed in code review165- `moved` blocks for renames, `removed` with `lifecycle { destroy = false }` to forget166- `prevent_destroy` on state-like resources (databases, volumes) and VM templates167168### DON'T169- Run `apply` without a saved plan outside a throwaway lab; use `-target` as a routine tool170- Run `state push -force` or `force-unlock` without proof of the cause171- Mix `tofu` and `terraform` on one state; commit `.tfstate`, plan files or `.tfvars` with secrets