Skip to content

UniFi inventory and field audit

What: two scripts that make the UniFi controller visible as files, and the adoption of every port profile, every switch’s ports, the site settings and the AP groups into tf/unifi, each at zero change. This is the design of the OpenSpec change unifi-inventory-and-field-audit, copied here because it changes an operational pattern: the field audit is now the gate before any import.

See proposal.md, Why, for the motivation. The facts below shape the approach.

  • tf/unifi (workspace main-cluster-unifi, auto-apply on merge) manages nine unifi_network resources and one unifi_device_ports resource for switch-main. The provider is the fork at app.terraform.io/fzymgc-house/unifi, pinned to 0.56.0-fzymgc.2 in versions.tf. The fork checkout is /Volumes/Code/github.com/fzymgc-house/terraform-provider-unifi, branch fzymgc. Its go.mod replaces github.com/ubiquiti-community/go-unifi with github.com/fzymgc-house/go-unifi, checkout /Volumes/Code/github.com/fzymgc-house/go-unifi, branch fzymgc.
  • go-unifi models each REST collection as a Go struct with a JSON tag per field. The generated files carry the path they serve, for example PortProfile in unifi/port_profile.generated.go serves rest/portconf. Site settings are one struct per section under unifi/settings/, keyed by the section’s key, and the provider writes a section with set/setting/<key>, which replaces the section. AP groups are APGroup in unifi/ap_group.go on the v2 path apgroups.
  • A typed struct drops unknown keys on decode, and a PUT through it replaces the whole object. So a field the struct does not tag is deleted on the first update, and no plan shows it. The fork’s unifi_device_ports resource escapes this by reading and writing the device record as raw JSON through the exported ApiClient.Do. Every other resource this change adopts is typed.
  • The spike session helper .planning/spikes/001-networkconf-guard-fields/unifi_session.py logs in at /api/auth/login, carries the cookie and CSRF token, verifies TLS against the system store, and its strip_secrets drops every x_ key. The credential comes from Vault at secret/fzymgc-house/infrastructure/unifi/readonly, a Network View Only account.
  • Measured on 2026-09-28 from stat/device: seven switches besides switch-main. switch-agg-main (USW-Aggregation), switch-office (USW-Pro-Max-16), switch-kitchen (USW-Flex-2.5G), switch-library (5-port Flex Mini PoE), switch-familyroom and switch-recroom (US-8), switch-masterbedroom (US-8-60W). Four port profiles exist: AllMainDefault, NoNativeNet, AllServer, MobileInternet. switch-office, switch-kitchen and switch-library bind ports to AllMainDefault. The controller has no adopted access point, so the AP group collection is the default group with an empty member list.
  • Two fork gaps found on 2026-09-28 while reading the provider source. unifi_port_profile gives dot1x_idle_timeout a schema default of 5m0s (unifi/port_profile_resource.go, stringdefault.StaticString), and MobileInternet holds no such key on the controller, so it imports with one change. unifi_device_ports already declares port_profile_id, mapped to the controller’s portconf_id, with declared port settings taking precedence over the profile. An earlier reading of this design said the key was missing. It was not.
  • The sibling change unifi-networks-gateway-ready plans two unifi_device_ports resources for the UX7 access point ports, switch-office 13 and switch-familyroom 8. Two resources on one MAC overwrite each other.

The addressing authority is docs/reference/network.md. This change allocates no address and no prefix.

Goals:

  • One command dumps the controller. One command names the fork’s gaps per collection. Both run from a workstation with the View Only credential and write nothing secret into the repository.
  • The audit is the gate. A typed collection is imported only after the audit prints no gap for it on the fork commit the pin points at.
  • Every tier-one object imports at zero change, with the same plan proof the networks passed.
  • One unifi_device_ports resource per switch, whichever change lands first.

Non-Goals:

  • No apply of a change to the controller beyond the imports and the fields they state. The dead firewall-uplink aggregation on switch-main is removed by unifi-networks-gateway-ready.
  • No adoption of a tier-two or tier-three collection. The runbook table names them.
  • No management of a setting section the fork does not model, and no unifi_device resource.
  • No history. The admin activity log stays a manual probe.

D1. Two scripts under scripts/, one shared session module, one credential wrapper

Section titled “D1. Two scripts under scripts/, one shared session module, one credential wrapper”

scripts/unifi-inventory.py and scripts/unifi-field-audit.py are stdlib-only uv run --script files, like scripts/dns-vip-holder.py. scripts/unifi_session.py is the spike helper, moved without change so both scripts import it from their own directory. scripts/unifi-readonly.sh is the spike’s run.sh: it reads the Vault credential into UNIFI_USERNAME and UNIFI_PASSWORD and executes the script it is given. The spike directory keeps a one-line pointer to the new location.

Alternative rejected: a Go tool in the provider fork that reuses go-unifi’s client. It would tie the inventory to a provider build, and the cutover needs the inventory on a workstation with no Go toolchain assumption.

D2. The inventory knows its collections from a list in the script

Section titled “D2. The inventory knows its collections from a list in the script”

The list is the union of the REST collections go-unifi serves under rest/, the v2 collections it serves under v2/api/site/default/, and stat/device. The rest/ set on the fork today is: account, broadcastgroup, channelplan, dashboard, device, dhcpoption, dpiapp, dpigroup, dynamicdns, firewallgroup, firewallrule, heatmap, heatmappoint, hotspot, hotspotop, hotspotpackage, map, mediafile, networkconf, portconf, portforward, radiusprofile, routing, scheduletask, setting, spatialrecord, tag, user, usergroup, virtualdevice, wlanconf, wlangroup. The v2 set is apgroups, bgp/config, firewall/zone, firewall-policies, nat, network-members-groups, ospf/router, power-supervisors, static-dns, trafficroutes, wireguard, device-tags. Each entry names the file it writes and the go-unifi struct that models it, or none. Measured on 2026-09-28 against Network 10.6.106: nine of those rest/ collections answer HTTP 400 (broadcastgroup, dashboard, heatmap, heatmappoint, hotspot, map, mediafile, tag, virtualdevice) and rest/device answers 404, so the list leaves them out and reads devices through stat/device. WireGuard peers live under a per-network path and join the list when a WireGuard network exists.

A collection the controller refuses (401, 403, 404) is reported on standard error, and the run continues, so a dump of an older or newer Network version still covers everything it can. The exit code is non-zero when any collection was refused, so the cutover diff is never read as complete when it is not.

Alternative rejected: discovering collections by parsing go-unifi at run time. The audit needs the fork checkout anyway, but the inventory has to run on the cutover bench without it.

D3. The dump goes to a named directory, and the summary goes to the repository

Section titled “D3. The dump goes to a named directory, and the summary goes to the repository”

The inventory writes <dir>/<collection>.json with every x_ key removed at every depth, and prints a summary: per collection, the object count and the sorted union of keys. The summary is committed as tf/unifi/inventory-summary.json, next to the consumer. Terraform ignores a non-.tf file in its root. The summary holds no value, only key names and counts, so client names and passphrases never enter Git.

Two dumps of the same controller produce the same summary, because keys are sorted and counts are integers. Two dumps across a restore are compared with diff -r on the directories after a normaliser drops _id, site_id and the timestamp keys the controller rewrites on restore (attr_no_delete and attr_hidden_id stay, because they carry intent). The normaliser is a flag on the inventory script, --for-diff, so the cutover runbook is one command per dump and one diff.

D4. The audit reads JSON tags from the fork checkout at a named commit

Section titled “D4. The audit reads JSON tags from the fork checkout at a named commit”

unifi-field-audit.py <dump-dir> --go-unifi <checkout> [--tier one|two|all] parses the struct that D2 pairs with each collection and collects its JSON tag names, including nested structs and embedded BaseSetting. A tag that starts with x_ is ignored, because the dump has none. For setting, each object is audited against the section struct that matches its key under unifi/settings/, and a section with no struct is listed as unmodelled. The audit prints, per collection or section, no gap or one line per missing key with the number of objects that carry it. The exit code is non-zero when any collection in the requested tier has a gap.

The audit records the fork commit it read (git -C <checkout> rev-parse HEAD) in its output, so a no gap is tied to a commit. The gate for an import is: the audit prints no gap for the collection at the go-unifi commit that the provider release in versions.tf was built from.

Alternative rejected: comparing against the Terraform provider schema instead of the wire struct. The schema is what a person can declare. The wire struct is what the update sends. The deletion hazard lives in the second, so the audit reads the second. Where the schema is narrower than the struct, the field survives an update but cannot be declared, and the runbook says so.

D5. One fork release closes the known gaps before any import

Section titled “D5. One fork release closes the known gaps before any import”

Release 0.56.0-fzymgc.3 of the provider carries three changes on branch fzymgc:

  1. unifi_port_profile.dot1x_idle_timeout loses its schema default and stays Optional and Computed with UseStateForUnknown. Import reads the controller value when present and leaves the attribute null when absent, the same fix the networks needed for their six fields. A schema test asserts that no default exists, and a conversion test asserts that an absent key reads as null.
  2. unifi_setting gains the global_switch section (D8), read first and overlaid, the pattern igmp_snooping uses.
  3. The go-unifi replace moves to the commit that tags the fields the audit found on 2026-09-28: external_id and ipv6_enabled on Network and its corporate, guest and vlan-only encoders, nine keys on PortProfile, three on settings.GlobalSwitch, one on settings.IgmpSnooping and for_wlanconf on APGroup. Every new scalar is a pointer with omitempty, so an absent key stays absent and a stored false or zero survives.

unifi_device_ports needs no change. It already declares port_profile_id. The convention in D6, a profile-bound port states only port_profile_id, is a tf/unifi convention and not a provider validator, because the controller accepts both and documents that declared port settings win. The runbook docs/operations/terraform-provider-fork.md has the release steps.

Wire structs for every managed field: unifi.PortProfile for unifi_port_profile, the raw port_overrides array of the rest/device record for unifi_device_ports, settings.Mgmt, settings.Ntp, settings.IgmpSnooping, settings.Rsyslogd for the unifi_setting sections this change adopts, and unifi.APGroup for unifi_ap_group.

D6. Port profiles are resources, and bound ports reference them

Section titled “D6. Port profiles are resources, and bound ports reference them”

The four profiles become unifi_port_profile resources in tf/unifi/port-profiles.tf, imported by _id, stating the fields that differ from the provider defaults, as networks.tf does. A port that carries a profile on the controller declares port_profile_id = unifi_port_profile.<name>.id and nothing else about networks. A port that carries no profile declares its network keys, as ports.tf does. This settles issue #2146’s open question in favour of profiles, because three switches already use one and dropping it would be a write to nine ports, not an adoption.

Alternative rejected: stating each profile’s settings on every bound port and leaving profiles unmanaged. That turns four objects into one setting block per port and hides that the ports share one intent.

D7. One unifi_device_ports resource per switch, named ports-<switch>.tf

Section titled “D7. One unifi_device_ports resource per switch, named ports-<switch>.tf”

Each of the seven switches gets tf/unifi/ports-<name>.tf with a locals MAC, one resource, prevent_destroy, and an import block in main.tf, the shape of ports.tf. Only ports whose settings differ from the controller default are listed, the verbosity rule from #2131. The two UX7 access point ports that unifi-networks-gateway-ready plans are entries in ports-office.tf and ports-familyroom.tf. Whichever change lands first creates the file with its import block, and the other adds its entries to it. The sibling’s proposal states the same rule, so the landing order carries no risk. Prerequisite: neither change’s port pull request merges while the other proposal still plans a second resource on the same MAC.

Rollback for an import is terraform state rm <address> on the workspace, which leaves the controller untouched. No import in this change writes to the controller when the plan is clean.

D8. Settings: adopt the sections the fork models and the estate depends on

Section titled “D8. Settings: adopt the sections the fork models and the estate depends on”

tf/unifi/settings.tf declares one unifi_setting resource for site default, imported by the site name, with the sections mgmt (auto-upgrade and SSH), ntp, igmp_snooping and syslog when the controller holds a non-default value in them. Every other section stays out. The global_switch section holds dhcp_snoop, the switch-wide setting that DHCP Guard depends on. go-unifi models it (settings.GlobalSwitch), but the provider’s unifi_setting resource does not expose it. Adding the section to the provider goes into the same fork release as D5 when the audit prints no gap for global_switch. If the audit prints a gap, the section stays controller-owned and the runbook lists it.

Rollback for a setting change is a revert commit. The workspace auto-applies the previous values with set/setting/<key>. Nothing in this change plans a setting change. The import states the live values.

tf/unifi/ap-groups.tf declares the default group as unifi_ap_group with the member list the controller holds today. unifi-wifi-cutover adds the access points to it. Adopting the empty group now means that change is an edit, not an import.

D10. The tier table is one table in the runbook

Section titled “D10. The tier table is one table in the runbook”

docs/operations/unifi.md gets a section, What Terraform manages, by tier, with one row per collection: now, after the cutover, or never, and for never the owner. Never: device (adoption and radios, a measured full-replace hazard), user (Kea owns addressing), static-dns and dynamicdns (the resolver pair and Cloudflare own names), radiusprofile and the site itself. The “Not managed” line in the current runbook goes.

D11. The inventory is a bench step in the cutover

Section titled “D11. The inventory is a bench step in the cutover”

ucg-fiber-gateway-cutover runs the inventory before the backup and after the restore and diffs them. This change gives it the commands and nothing else. The cutover proposal already names the step.

  • [The View Only account cannot read a collection the audit needs] → The inventory reports the refusal and exits non-zero. The operator reads that collection once with the admin credential in 1Password, by hand, and the summary records the fact. Nothing in the repository reads the admin credential except the workspace.
  • [A dump lands in the repository by mistake] → The inventory refuses to run without a directory argument and prints its usage. .gitignore gains *.unifi-dump/, and the runbook names the scratch path. Client names are household names, so a leaked dump is a privacy fault, not a security fault.
  • [The audit passes on one go-unifi commit and the provider pin points at another] → The audit prints the commit it read. The task that moves the pin also re-runs the audit at the go-unifi commit in the provider’s go.mod replace line.
  • [A profile-bound port also carries per-port network keys on the controller] → The controller keeps both. The declared entry states only port_profile_id, and the raw update leaves the other keys in place. The plan is clean because the resource compares declared keys only.
  • [The dot1x default fix changes state for existing users of the fork] → The fork’s only consumer is tf/unifi, which declares no profile yet. The state upgrader from the v1 schema migration stays in place.
  • [Seven imports in one pull request hide which switch drifts] → One or two switches per pull request, each with its own plan output pasted in the pull request body.
  • [Settings sections carry x_ keys, such as x_ssh_keys in mgmt] → The dump strips them, the audit ignores tags that start with x_, and the mgmt resource does not declare SSH keys. SSH keys for the switches stay controller-owned, and the runbook says so.
  1. Land the scripts and the committed summary. Run the audit for tier one and paste its output in the pull request.
  2. Release the provider 0.56.0-fzymgc.3 with D5 and, if the audit allows, D8’s global_switch section. Move the pin in versions.tf and lock both platforms.
  3. Import the four profiles. Plan must read 4 to import, 0 to add, 0 to change, 0 to destroy.
  4. Import the seven switches, one or two per pull request, profile-bound ports referencing D6’s resources. Each plan reads N to import, 0 to add, 0 to change, 0 to destroy.
  5. Import the setting sections and the AP group.
  6. Update the runbook with the tier table and the inventory commands, and copy this design to docs/engineering/specs/2026-09-28-unifi-inventory-and-field-audit-design.md.

Rollback at any step: terraform state rm for an import, a revert commit for a declared value. No step changes traffic.

  • Which syslog target the controller holds, and whether it is the OpenTelemetry collector or nothing. The inventory answers it, and the section is declared only if a value is set. The task list does not change either way.