Changelog 2026-07-09 -- OpenTofu module audit pass (DOCFIX-148)

No live infrastructure touched -- documentation/comment corrections only, plus confirmatory research. Operator asked to pull documentation for anything drafted without it and review all 9 modules built this session for errors/assumptions, after DOCFIX-142/144/145/146/147 had already shipped.

Item

1. DOCFIX-148 -- audited every flagged UNVERIFIED/inferred/assumed note

FILES: opentofu/modules/opnsense-edge/{main,variables}.tf, opentofu/modules/node-vm/main.tf, opentofu/modules/maas-vm-host/variables.tf, scripts/opnsense-build-config-iso.sh, opentofu/README.md.

METHOD: grepped the entire opentofu/ tree for every "UNVERIFIED"/"NOT confirmed"/"inference"/"assumed"/"not independently" marker left by prior deliveries, then researched each one further (libvirt's own official XML docs, a second independent source on the provider's volume-fetch mechanism, FreeBSD/OPNsense interface-naming documentation, genisoimage reference docs, MAAS provider zone/pool behavior) rather than re-stating the same hedge unchanged.

One genuine error found and fixed, not just a hedge re-confirmed: opnsense-edge's comments claimed devices.interfaces list order ("index 0 = LAN") directly determines OPNsense's LAN/WAN role. Researching FreeBSD/OPNsense's interface-assignment model showed this conflates two separate things: list order plausibly controls which vtnetN device number a NIC gets (libvirt's own PCI-addressing docs: auto-assigned addresses "usually match" XML order for a simple topology), but OPNsense's actual LAN/WAN designation is a SEPARATE, explicit mapping set inside config.xml itself (or the interactive/API assignment step) -- "vtnet0 = WAN" is a convention some guides choose, not an enforced rule. main.tf's comments and both lan_network_name/wan_network_name variable descriptions rewritten to state this correctly: the variables express intent for which network should end up as which role, but whoever writes the still-undesigned config.xml must independently confirm the real vtnetN<->network mapping on a boot and set <wan>/<lan> accordingly. No config.xml has been written yet in this repo, so this corrects documentation accuracy for a future author, not current runtime behavior.

Confidence upgraded (not resolved outright) on three other items:

• node-vm's boot = { order = N } shape: confirmed the provider code-generates its schema as a 1:1 mirror of libvirt's own domain XML (an architectural fact not visible in the resource doc pages alone), and confirmed libvirt's own docs show the native element is exactly <boot order='N'/> -- consistent with the established single-attribute mapping pattern already seen elsewhere in this schema. Still recommend a real tofu providers schema -json check before trusting it, but this is reasoned support now, not a bare guess.
• create.content.url accepting local filesystem paths: corroborated by a second, independent source describing the underlying fetch mechanism as supporting local paths alongside remote URLs.
• genisoimage/xorriso invocation flags (-V/-J/-R): confirmed as standard, correct usage for a plain cross-platform ISO9660 image -- separated cleanly from the genuinely still-open question (whether OPNsense's Importer actually reads the result on a real boot), which remains unverified.

Confirmed safe, previously assumed: maas_vm_host's zone/pool being computed by MAAS when left unset -- validates the default = null design choice in modules/maas-vm-host as a supported no-op.

Deliberately NOT re-researched: findings already backed by a primary, authoritative source on the first pass (the OPNsense Configuration Importer mechanism itself, the maas_vm_host vs. maas_vm_host_machine distinction, the provider's attribute-vs-block syntax fix) -- re-verifying already-solid findings on every audit would be its own kind of waste; the audit targeted specifically the notes marked as gaps.

opentofu/README.md gained a new "Audit pass (2026-07-09)" section documenting all of the above with reasoning, positioned as its own dated entry alongside the existing OPNsense and MAAS/netem research sections rather than silently editing history.

2. Documentation references added to the openstack-cloud-ops skill

FILE (new): .claude/skills/openstack-cloud-ops/references/opentofu-provider-docs.md. FILES (modified): .claude/skills/openstack-cloud-ops/SKILL.md (new routing entry), opentofu/README.md (cross-reference back to the skill file).

WHAT: operator asked for documentation links/access to be added to the skill so future sessions can reference the direct sources rather than rediscovering them. The new file indexes every provider/doc source used building opentofu/ (dmacvicar/libvirt, canonical/maas, OpenTofu's own local-exec/terraform_data docs, OPNsense's docs/forum/GitHub issues) with their exact URLs, confirmed versions, and default branches -- plus, more valuably than the links alone, the FETCH METHODOLOGY that actually worked this session: the Registry's own doc pages are JS-rendered and return empty shells on a plain fetch (go to the provider's GitHub repo instead); GitHub raw-file branch names vary and should be checked via the API's default_branch field, not assumed; a general web search's own summary can itself be wrong (encountered once); asking for "bare field names only" gets past copyright-caution refusals that "reproduce this page" trips; real example .tf files are consistently more reliable than doc-summarized prose for syntax questions (the root cause of the DOCFIX-142 syntax bug this whole delivery arc has referenced).

Deliberately does NOT duplicate the per-module findings themselves (schema notes, what's confirmed vs. assumed per attribute) -- that stays in opentofu/README.md as the single source of truth, cross-referenced from both directions, so it can't drift into two disagreeing copies.

REVERT: git rm .claude/skills/openstack-cloud-ops/references/opentofu-provider-docs.md; revert the two cross-reference edits if reverting fully.

REVERT: git checkout HEAD~ -- opentofu/modules/opnsense-edge opentofu/modules/node-vm/main.tf opentofu/modules/maas-vm-host/variables.tf scripts/opnsense-build-config-iso.sh opentofu/README.md (re-arms the LAN/WAN documentation error -- not recommended).