ADR-0009: Network Device Configuration Is Inventory-Owned and Controller-Applied #

Context #

The mobile site’s network devices are configured three different ways today:

• The access switch is configured by the switch_vlans role over its CLI, from inventory: deevnet_vlans declares the VLANs, and switch_ports in host_vars/dv02acc001p01.yml declares every trunk, native VLAN and access port.
• The AP’s SSIDs were configured by hand in its own web UI, because the controller could not push VLAN-tagged SSIDs to its 2023 firmware ( CHG-0001).
• The Omada controller holds hand-grown, partial state: six networks created by a migration playbook in March, and nothing else. It has never adopted the switch.

CHG-0004 brings the controller and both devices’ firmware current, so that Omada can manage them. That raises the question this record settles. Adopting a device hands its configuration to the controller, so something has to own that configuration: inventory, or the controller.

Two things make the question pressing rather than academic.

• Adoption is not neutral. On adoption the controller applies its own port profile. The built-in All profile is native VLAN 1 with every other network tagged. Adopted as it stands, the live switch would move the builder’s port and the uplink onto VLAN 1, and the builder runs the controller, so the controller would cut its own path mid-adoption. That is the failure shape of INC-0001: the automation host behind the thing it is changing.
• switch_vlans is the weakest role in the estate. It drives the CLI through cli_command, which reports every run as changed, and its --check fails on every configuration line. It cannot say what a run is about to do.

Options considered #

A — The controller owns the configuration #

Configure the site in the controller’s UI, and let its database be the record.

Rejected. The controller’s database would become the only copy of the network’s configuration. It is also one-way across upgrades — a newer controller’s database cannot be opened by an older one — so losing it, or falling back a version, loses configuration ( Omada Controller Recovery). That runs against the substrate’s premise that everything is declared in git and rebuilt from it.

B — Inventory owns it, applied over the CLI; the controller only watches #

Keep switch_vlans, and do not adopt the switch.

Rejected. It leaves the weakest role as the switch’s only mechanism, and it leaves the AP on hand-set SSIDs, because the controller is what provisions an adopted AP. A switch cannot be both controller-managed and configured over its CLI: a CLI change to a managed switch is overwritten at the controller’s next provision.

C — Inventory owns it; the controller applies it #

Inventory stays the only declaration. Automation turns it into controller objects through the controller’s API, and the controller pushes them to the devices.

Chosen.

Decision #

1. Inventory is the only source of network device configuration #

deevnet_vlans, switch_ports and the SSID definitions stay as they are. The controller’s database is derived state: whatever it holds can be rebuilt from inventory by re-running the automation.

2. The controller is the actuator #

Automation applies inventory through the controller’s API. The controller then provisions the devices. Nobody configures a managed device in the controller’s UI, or on the device.

3. The documented Open API first; undocumented calls only as a marked fallback #

• “Documented” means the spec the running controller publishes at /v3/api-docs — 1,856 paths on 6.3.0.45. That spec, not a vendor web page, is what automation checks itself against.

• An undocumented /api/v2 call is allowed only where the documented API cannot do the job.

• Every call site is marked, in one greppable form:

  # omada-api: documented <operationId> spec <controller version>
  # omada-api: UNDOCUMENTED <path> tested-on <controller version>
  

• On a controller upgrade, grep -rn "omada-api: UNDOCUMENTED" lists what to re-test by hand. Automation also checks, before it writes, that every documented endpoint it uses is present in the running controller’s spec, and refuses to run if one has gone.

4. switch_vlans is break-glass for an adopted switch #

A switch declares switch_management: omada in host_vars when it is adopted. From then on, switch_vlans refuses to run against it. The only way past that is a per-run -e switch_vlans_break_glass=true, and it is for one situation only: the controller cannot be used, and the switch has first been returned to standalone (forgotten, or factory reset). The run announces itself as break-glass. Adopting the switch again afterwards puts it back under the controller, which re-applies the same inventory.

A switch that has not been adopted is standalone, and switch_vlans remains its tool.

5. The manual floor is short, and written down #

What must exist before automation can do anything:

6. Define the site first, then adopt, then provision #

1. Create the site-level objects through the API: networks from deevnet_vlans, and one port profile per distinct port shape in switch_ports.
2. Adopt the device.
3. Assign each port its profile, and set the device’s name and management VLAN and IP.
4. Verify reachability.

For a switch already in service, adoption is done as a planned rebuild: factory reset, adopt, provision from inventory. The console-recovery procedure already treats a reset as legitimate, because everything worth keeping is in inventory. A new site, a recovery and an adoption then follow the same path.

7. The API role carries INC-0001’s guards from the start #

• Refuse to reconcile from an empty or partial desired set.
• Deletion of objects inventory does not declare is off by default, and reported rather than done.
• The ports carrying the controller’s own path — the uplink and the builder’s port — and the management VLAN are protected from change.
• Reachability is checked after every apply.

Consequences #

What this buys:

• A lost controller is an inconvenience, not a data loss. Reinstall it and re-run the automation. The snapshot-and-fallback care CHG-0004 needed matters much less once nothing lives only in the controller.
• One mechanism for the switch and the AP, SSIDs included, that can report what it will change, instead of a CLI role that always says “changed”.
• Version bumps become checkable: diff the published spec, and sweep the markers.
• The translation forces good declarations. An Omada profile requires STP, LLDP-MED and loop detection, so each becomes a stated choice rather than a firmware default that can move underneath the configuration.

What it costs:

• Changes need the controller. While it is down, adopted devices keep forwarding but cannot be changed, except by break-glass, which means taking the switch back to standalone.
• The manual floor grows by one Open API client, and the adoption window has to run with the builder bootstrap-authoritative, or with the switch’s address set by hand.
• The first run has to reconcile, not assume an empty controller, because six networks from March are already there, named by a different convention.
• Two schema rules need encoding. An Omada profile cannot list its native VLAN as tagged, though inventory lists it in both places, so the role subtracts it.
• switch_vlans, and the runbook steps that call it, become break-glass for adopted switches. The runbook pages change when a switch is actually adopted.

Evidence #

Gathered on 2026-09-10 against controller 6.3.0.45. The discovery calls were read-only; nothing was written to the controller.