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.
Context
Section titled “Context”See proposal.md, Why, for the motivation. The facts below shape the approach.
tf/unifi(workspacemain-cluster-unifi, auto-apply on merge) manages nineunifi_networkresources and oneunifi_device_portsresource for switch-main. The provider is the fork atapp.terraform.io/fzymgc-house/unifi, pinned to0.56.0-fzymgc.2inversions.tf. The fork checkout is/Volumes/Code/github.com/fzymgc-house/terraform-provider-unifi, branchfzymgc. Itsgo.modreplacesgithub.com/ubiquiti-community/go-unifiwithgithub.com/fzymgc-house/go-unifi, checkout/Volumes/Code/github.com/fzymgc-house/go-unifi, branchfzymgc.- 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
PortProfileinunifi/port_profile.generated.goservesrest/portconf. Site settings are one struct per section underunifi/settings/, keyed by the section’skey, and the provider writes a section withset/setting/<key>, which replaces the section. AP groups areAPGroupinunifi/ap_group.goon the v2 pathapgroups. - 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_portsresource escapes this by reading and writing the device record as raw JSON through the exportedApiClient.Do. Every other resource this change adopts is typed. - The spike session helper
.planning/spikes/001-networkconf-guard-fields/unifi_session.pylogs in at/api/auth/login, carries the cookie and CSRF token, verifies TLS against the system store, and itsstrip_secretsdrops everyx_key. The credential comes from Vault atsecret/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 toAllMainDefault. 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_profilegivesdot1x_idle_timeouta schema default of5m0s(unifi/port_profile_resource.go,stringdefault.StaticString), andMobileInternetholds no such key on the controller, so it imports with one change.unifi_device_portsalready declaresport_profile_id, mapped to the controller’sportconf_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-readyplans twounifi_device_portsresources 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 / Non-Goals
Section titled “Goals / Non-Goals”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 gapfor 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_portsresource 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-uplinkaggregation on switch-main is removed byunifi-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_deviceresource. - No history. The admin activity log stays a manual probe.
Decisions
Section titled “Decisions”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:
unifi_port_profile.dot1x_idle_timeoutloses its schema default and stays Optional and Computed withUseStateForUnknown. 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.unifi_settinggains theglobal_switchsection (D8), read first and overlaid, the patternigmp_snoopinguses.- The go-unifi replace moves to the commit that tags the fields the audit found on 2026-09-28:
external_idandipv6_enabledonNetworkand its corporate, guest and vlan-only encoders, nine keys onPortProfile, three onsettings.GlobalSwitch, one onsettings.IgmpSnoopingandfor_wlanconfonAPGroup. Every new scalar is a pointer withomitempty, 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.
D9. AP groups are adopted now, empty
Section titled “D9. AP groups are adopted now, empty”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.
Risks / Trade-offs
Section titled “Risks / Trade-offs”- [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.
.gitignoregains*.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.modreplace 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 asx_ssh_keysinmgmt] → The dump strips them, the audit ignores tags that start withx_, and themgmtresource does not declare SSH keys. SSH keys for the switches stay controller-owned, and the runbook says so.
Migration Plan
Section titled “Migration Plan”- Land the scripts and the committed summary. Run the audit for tier one and paste its output in the pull request.
- Release the provider
0.56.0-fzymgc.3with D5 and, if the audit allows, D8’sglobal_switchsection. Move the pin inversions.tfand lock both platforms. - Import the four profiles. Plan must read
4 to import, 0 to add, 0 to change, 0 to destroy. - 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. - Import the setting sections and the AP group.
- 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.
Open Questions
Section titled “Open Questions”- Which
syslogtarget 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.