# 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).