# Changelog 2026-07-09 -- MAAS VM-host registration + tc netem modules (DOCFIX-147)

No live infrastructure touched -- unapplied IaC only. Researched against
official sources before drafting (operator instruction this turn), not
inferred from memory -- continues the DOCFIX-142/144/145/146 OpenTofu build.

## Items

### 1. DOCFIX-147 -- `opentofu/modules/maas-vm-host`
FILES (new): `opentofu/modules/maas-vm-host/{main,variables,outputs}.tf`;
root `versions.tf`/`variables.tf`/`main.tf` gained the `canonical/maas`
provider (v2.7.2, confirmed from the registry's own metadata, not guessed)
plus `maas_api_url`/`maas_api_key` variables (`maas_api_key` marked
`sensitive = true`).

WHAT: registers the vcloud host's virsh/libvirt connection with MAAS as a
VM host (D-103: "OpenTofu registers each DC's libvirt host to that DC's MAAS
rack controller as a virsh VM-host, so MAAS DISCOVERS the OpenTofu-created
node VMs").

VERIFICATION, the point of this delivery: read both `maas_vm_host` and
`maas_vm_host_machine`'s real schemas (fetched from
`canonical/terraform-provider-maas`'s own `docs/resources/*.md`) before
picking one. `maas_vm_host_machine` takes `cores`/`memory`/`storage_disks`/
`network_interfaces` as INPUT arguments -- MAAS's own "Compose machine" pod
feature, where you specify desired specs and MAAS creates a new VM itself
via the virsh connection. D-103 explicitly rules this out ("MAAS ... does
NOT compose new ones"). `maas_vm_host` (register the chassis; MAAS's own
discovery then enlists whatever domains already exist) is the one that
matches D-103's actual described flow, where `modules/node-vm` already
pre-creates the VMs. Using `vm_host_machine` here would have MAAS and
OpenTofu fighting over VM creation -- a real design mistake this research
step caught before any code was written, not after.

Not instantiated: needs a real MAAS zone/pool and the vcloud host's real
`power_address` (confirmed format `qemu+ssh://user@host/system` from the
provider's own docs example -- same shape as this module's existing
`libvirt_uri` variable, kept as an independent input rather than assumed
identical).

### 2. DOCFIX-147 (cont.) -- `opentofu/modules/netem-link`
FILES (new): `opentofu/modules/netem-link/{main,variables,outputs}.tf`.

WHAT: applies `tc qdisc ... netem` WAN-simulation parameters (D-100) to a
`modules/mesh-link` bridge -- the mechanism flagged as missing in every
prior OpenTofu changelog this session ("needs either a null_resource
provisioner or a small companion script -- not yet written").

VERIFICATION: fetched OpenTofu's own official docs for `local-exec` and
`terraform_data` before drafting. Two findings that materially shaped the
design: (a) OpenTofu's own docs recommend `terraform_data` over the older
`null_resource` for exactly this "provisioner with no logical resource to
attach to" case -- used here, not `null_resource`. (b) `local-exec` runs on
the machine invoking `tofu apply` (Office1, per D-103), NOT on the vcloud
host where the bridge interfaces actually exist -- a bare local command
would silently do nothing useful. The module wraps the command in an
explicit SSH hop to the vcloud host instead. `tc qdisc replace` (not `add`)
is used so a re-apply is idempotent. A destroy-time provisioner
(`when = destroy`) removes the qdisc on teardown.

Not instantiated: needs the real bridge name (reading a `libvirt_network`'s
`bridge` attribute back was already flagged unconfirmed in `mesh-link`'s
outputs.tf, so this is a required, explicit input, not auto-derived), the
vcloud host's SSH target, and the actual netem parameters -- still an
unruled D-100 open item.

`opentofu/README.md` gained a new "MAAS registration + tc netem research"
section (mirroring the OPNsense research section's structure) with full
sourcing, and updated schema notes for `maas_vm_host`, the `maas` provider
block, and `terraform_data`. Workflow doc (Stage 3/4 authoring notes, gap
register items 2/4, summary table) and the companion visual tracker updated
to match.

REVERT: `git rm -r opentofu/modules/maas-vm-host opentofu/modules/netem-link`;
revert `opentofu/versions.tf`/`variables.tf`/`main.tf`'s maas-provider
additions and the doc sections if reverting fully.

## Next actionable step

Same underlying need as every prior OpenTofu delivery this session: a
machine with the `tofu` binary to run `scripts/opentofu-validate.sh` against
all of `opentofu/` -- this would catch any remaining schema mistakes at
once, the same way it would have caught the DOCFIX-142 syntax bug
immediately had it been available then.