Changelog 2026-07-09 -- OpenTofu node-VM module + syntax-bug fix (DOCFIX-144)

No live infrastructure touched -- unapplied IaC source only. Continues the DOCFIX-142 OpenTofu scaffold.

Items

1. DOCFIX-144 -- opentofu/modules/node-vm (D-103's PXE-boot node-VM pattern)

FILES (new): opentofu/modules/node-vm/variables.tf, main.tf, outputs.tf.

WHAT: one MAAS-managed OpenStack node VM per call -- a blank libvirt_volume boot disk (no image, no cloud-init) plus a libvirt_domain with PXE boot priority on its first network interface. This is the D-103 "OpenTofu creates the node-VM libvirt domains (SHIM)" need for buildout-design Stage 3 / Phase 2. Deliberately NOT the cloud-init/pre-built-image pattern (confirmed as a separate, distinct provider mechanism via a real example file -- see item 2 -- but not built as its own module this session; needed for Office1 service VMs and OPNsense instead).

VERIFICATION: this time, built from the provider's own real, runnable example files (examples/domain_with_network.tf, examples/alpine_cloudinit.tf -- fetched and read directly, not summarized-and-guessed) rather than doc-summarization passes alone, after the previous session's attempt at libvirt_domain was deferred for exactly that reason. Every attribute in main.tf is used in the same shape as a real example, EXCEPT one, flagged explicitly in the file and in opentofu/README.md: the per-device boot attribute's internal shape ({ order = N }) is an inference by pattern (confirmed to exist as a field name on both interfaces[] and disks[], matching native libvirt's per-device <boot order='N'/>, but not independently confirmed from a real example this session). Flagged as the first thing to check with tofu providers schema -json before relying on PXE-first boot working as written.

NOT instantiated in root main.tf: node count, memory, vcpu, and disk sizing are a Phase-0 host/disk-budget decision (buildout-design Section 3) that hasn't been made. Call the module once real values exist -- no placeholder specs invented to wire it in sooner.

2. DOCFIX-144 (cont.) -- real syntax bug found and fixed in the DOCFIX-142 delivery

FILES: opentofu/modules/dc-planes/main.tf, opentofu/modules/mesh-link/main.tf, opentofu/modules/dc-storage-pool/main.tf.

WHAT: all three originally used classic HCL block syntax for nested structures (domain { name = ... }, mtu { size = ... }, target { path = ... }). Building the node-VM module required fetching real example .tf files from the provider's repo, which showed those examples consistently use attribute-style nested OBJECTS instead (os = { ... }, devices = { ... }, target = { format = { ... } }) -- a provider-wide schema convention (this provider's current major version appears to use a terraform-plugin-framework object-typed-attribute schema mirroring raw libvirt XML, not classic blocks). All three files corrected to match; each carries a syntax-note comment explaining the change and its verification source.

WHY THIS MATTERS: this was a real correctness bug in already-committed, already-pushed code (DOCFIX-142, commit 14d7382) -- not caught by repo-lint (it checks encoding/staleness, not HCL semantics) and not catchable without either a real tofu validate pass (unavailable this session, still) or, as it turned out, real example code from the provider itself. Logged plainly rather than glossed over: the doc-summarization verification process used for DOCFIX-142 was insufficient on its own: it correctly identified WHICH fields exist, but could not reliably convey HOW they're called (block vs. attribute syntax). Real example code closed that gap; doc-summarization alone did not.

DOCUMENTED (not fixed, same class of remaining risk): opentofu/README.md's "Schema notes" section now states this attribute-object convention as a provider-wide assumption to apply to ANY nested field not personally confirmed otherwise -- since the reasoning that surfaced this bug (a handful of real examples, not an exhaustive schema dump) could plausibly have missed a resource-specific exception.

Next actionable step (unchanged, still logged not actioned)

On a machine with the tofu binary and registry network access: run bash scripts/opentofu-validate.sh against all of opentofu/ (this would have caught the DOCFIX-142 syntax bug immediately), then tofu providers schema -json to confirm the boot-order attribute shape before trusting PXE-first boot in modules/node-vm.

REVERT: git checkout HEAD~ -- opentofu/ (drops the node-vm module and reverts the three modules to their pre-fix, WRONG syntax -- not recommended).