Rebase the UniFi forks onto upstream
We move both UniFi forks from their 2026-08 base onto upstream main, re-carry our own work as a short
patch series, and release the result as provider 0.60.0-fzymgc.1. The approach is a replay, not a
git rebase. Each fork commit is re-applied by hand on a branch cut from upstream. Commits that
upstream now covers are dropped. The riskiest assumption is that upstream’s state upgraders accept the
state our fork wrote, so that tf/unifi plans no change after only a configuration rewrite.
Sean chose this path on 2026-10-16 over two alternatives: stay diverged and regenerate the models
ourselves, or stay diverged and hand-patch only what the site uses. The audit that led to the choice is
in the engram records dyg0yg2mkg and zkqn6atzr4. The facts it rests on are restated below.
Where the forks stand
Section titled “Where the forks stand”| Repository | Our base | Upstream main | Distance |
|---|---|---|---|
fzymgc-house/go-unifi branch fzymgc |
ead9900 plus 10 commits |
f52a177 (v1.36.0, models regenerated from Network 10.6.101) |
18 upstream commits |
fzymgc-house/terraform-provider-unifi branch fzymgc |
c16b66a plus 24 commits |
647cf534 (after v0.60.0-beta.0) |
69 upstream commits |
Upstream builds again. It regenerated the go-unifi models for Network 10.x, migrated the provider to
them, nested the prefixed attributes into objects, and shipped a state upgrader for every nested
resource. Our fork’s go-unifi models every key on every adopted collection. Upstream’s regenerated
models lack 12 keys we added by hand. Our fork also carries behavior upstream does not have:
unifi_device_ports, the raw Do request method, keep-live-keys-on-update for WLAN, WAN, BGP and
network, the radio table booleans as pointers, the radio_ai setting block, rrm_enabled,
passphrase_wo_version and dhcp_v6_server.allow_slaac.
Section 1. Decisions you will want to tweak
Section titled “Section 1. Decisions you will want to tweak”D1. Replay, not rebase. We cut fzymgc-next from upstream main in each repository and re-apply
our commits as a fresh series. A git rebase of 24 commits across a schema that upstream restructured
would conflict in every resource file. Changing this later costs nothing before work starts and
everything after.
D2. Version 0.60.0-fzymgc.1. Upstream’s next release is 0.60.0, now at beta.0. The runbook
names versions <next-upstream-minor>-fzymgc.<n>. The alternative is 0.61.0-fzymgc.1, which
leaves room if upstream tags 0.60.0 before we release. The pin is exact, so the choice costs one
line in tf/unifi/versions.tf either way. Decided 2026-10-16: 0.60.0-fzymgc.1.
D3. Hand-added keys move into the generator. The 12 keys that upstream’s regeneration lacks
(networkconf external_id, ipv6_enabled, routing_table_id, portconf
tagged_networkconf_ids, wlanconf external_id, passphrase_autogenerated, short_id, apgroups
for_wlanconf, bgp error, redistribute_to_sd_wan, firewall-zone cloud_template,
external_id, firewall-policies origin_id, radio_ai auto_enabled) are injected in
cmd/fields/main.go and cmd/fields/custom/*.json, as upstream does for mdns_enabled. Then we
regenerate from the 10.6.106 package. The alternative is to patch the generated files by hand, as the
fork did until now. The generator route costs more once and nothing on every later regeneration.
D4. unifi_device_ports follows upstream’s port_override shape. Upstream nests five groups
inside a port: dot1x, egress_rate_limit, lldpmed, port_security and stormctrl. Our resource
adopts the same five objects, with a state upgrader from the flat keys. Keys that upstream has no
shape for yet (stp_edge_state, stp_bpdu_guard_enabled, multicast_router_mode, lag_idx,
sd_wan_underlay_port) stay flat until upstream gives them one. In tf/unifi, three ports change
dot1x_ctrl and dot1x_idle_timeout into dot1x = { ctrl, idle_timeout }. The alternative was to
keep every key flat, which is cheaper now and diverges from upstream for good. Decided 2026-10-16:
follow upstream.
D5. Adopt upstream’s nested shapes everywhere else. tf/unifi changes: ipv6_* on 7 networks
becomes an ipv6 object, dhcp_v6_server.dns_auto becomes dns.auto, wpa_mode, wpa3_* and
ap_group_ids on 4 WLANs become wpa, wpa3 and ap_group objects, dot1x_idle_timeout and
lldpmed_* on 4 port profiles become objects, mgmt.auto_upgrade* and syslog.netconsole_*,
syslog.this_controller* in settings.tf become objects. Our flat roaming_assistant_*_enabled and
*_rssi attributes are dropped for upstream’s nested roaming_assistant_na and
roaming_assistant_6e. rrm_enabled has no upstream form and stays flat. The alternative, a
compatibility layer that accepts both shapes, doubles every schema and is not worth it for one site.
Decided 2026-10-16: adopt upstream’s shapes, drop our flat roaming assistant attributes.
D6. Keep-live-keys-on-update is re-carried. Upstream issue #583 shows unifi_wlan at 0.59.0
still zeroes fields it does not model on update. Our read-then-overlay code for WLAN, WAN, BGP and
network is re-applied on the new base. The alternative is to trust upstream’s per-field fixes. The
field audit gate below is what tells us which one holds.
D7. Branch mechanics. Work lands on fzymgc-next and is reviewed there. Then fzymgc is reset
to the new series with a force push, and the release tag is cut from its head. The old commits stay
reachable through the existing v0.56.0-fzymgc.* tags. The alternative was a merge commit into
fzymgc, which keeps two unrelated histories in one branch. Decided 2026-10-16: reset.
D8. The Integration API is a second plan. DNS policies, policy ordering, traffic matching lists and vouchers exist only on the official API, which needs an API key that Vault does not hold. This plan does not touch it.
Section 2. Known unknowns
Section titled “Section 2. Known unknowns”U1. State upgraders and our schema versions. Upstream’s upgraders map from upstream’s prior
schema versions. If a fork commit bumped a resource’s schema version that upstream did not, the
upgrader map misses and terraform plan fails with “no upgrade function”. Default: before release,
compare every resource’s Version between the fork at v0.56.0-fzymgc.16 and the new series, and add
a passthrough upgrader where they differ. Signal to pivot: the speculative plan errors on refresh.
U2. Generator conflicts. Upstream cleaned the generator (e70afb4) and repaired the 10.x
fallout (91a2ea4). Our injections land on that code. Default: regenerate from the cached 10.6.106
package and expect only the files that carry our keys to change. Signal: the regeneration diff
touches files outside that set.
U3. Static defaults on adopted objects. Upstream issue #544 names 138 Optional+Computed
attributes with static defaults that overwrite the controller’s value. Upstream fixed some in 0.59.0.
Default: the tf/unifi speculative plan is the detector. Signal: a planned change on an attribute the
configuration does not declare.
U4. The demo controller. The provider’s acceptance tests run a demo-mode controller in Docker. It does not run Network 10.6.106. Default: unit tests and acceptance tests gate the fork pull requests, and the live speculative plan gates the release.
U5. Dropped commits. Four fork commits have an upstream counterpart that is close but not
identical: the vlan-only import (a9214fc5, upstream #525), the global_switch block (283ab7b3,
upstream #513), setting import reads every section (3605939b) and the two inconsistent-result fixes
(df1e37e3). Default: drop each and rely on upstream. Signal: a failing unit test from the fork, or
a planned change on a tf/unifi object, brings the commit back.
Section 3. The mechanical work
Section titled “Section 3. The mechanical work”Each phase ends at a gate a person can run at a shell.
- go-unifi. Cut
fzymgc-nextfromupstream/main. Re-applydo.goand its tests. Move the 12 keys and the pointer booleans (radio_tablebools,mesh_sta_vap_enabled,switch_vlan_enabled, fork issue #24) into the generator. Merge ourcustom/*.jsonwith upstream’s. Rungo run ./cmd/fields -output-dir unifi 10.6.106. Re-apply thenetwork_encode.gochanges andcontroller_fields_test.go. Gate:go test ./...passes, andscripts/unifi-field-audit.py <dump> --go-unifi <checkout> --tier allprintsno gapfor every collection intf/unifiand names at most 14 gapped collections. - Provider. Cut
fzymgc-nextfromupstream/main. Point thego.modreplace at the new go-unifi commit. Re-apply, in this order: the release configuration and the publish script,unifi_device_portswith the port action, keep-live-keys for network, WLAN, WAN and BGP,passphrase_wo_version,ipv6_setting_preferenceandallow_slaac,rrm_enabled, theradio_aiblock, the radio table boolean send. ExtendTestPlanUnchangedConfigIsEmptytounifi_device_ports. Write the fork section ofCHANGELOG.md. Gate:go build ./...,go test ./..., and the acceptance suite against the demo controller pass. - Release. Reset
fzymgcto the reviewed series, tagv0.60.0-fzymgc.1, build with.goreleaser.fzymgc.yml, sign and publish perdocs/operations/terraform-provider-fork.md. Gate:terraform initintf/unifireportsself-signed, key ID 7B381B811D6398AD. - tf/unifi. One pull request: bump the pin, rewrite the attributes named in D5, run
terraform providers lock -platform=linux_arm64 -platform=darwin_arm64, updatedocs/operations/terraform-provider-fork.mdwith the new base commits. Gate: themain-cluster-unifispeculative plan showsNo changes. The rule stands: the pull request does not merge while the plan changes anything it does not declare. - Close out. Close fork issue #24. Narrow fork issue #20 to the fixed mesh parent, because upstream covers the minimum data rate and the roaming assistant. Record the new bases in engram. Open the second plan for the Integration API and the exposure work from the audit.
Review
Section titled “Review”Sean answered the four open questions on 2026-10-16. The answers are recorded next to D2, D4, D5 and D7 above. Work starts with phase 1.
Outcome
Section titled “Outcome”Phases 1 to 3 landed on 2026-10-17. go-unifi fzymgc is at 4329be4 on upstream f52a177, and the
provider fzymgc series is on upstream 647cf534. The release that tf/unifi pins is
v0.60.0-fzymgc.4, not .1. The first speculative plan against .1 found five provider faults,
and each took a fork release:
.2:unifi_networkreadipv6.setting_preferenceas null on every refresh, and the upstream plan-time refusal offorward = "customize"on an untagged native network rejected the liveAllServerprofile. The controller keepscustomizewhentagged_vlan_mgmtiscustomand a tagged network stays allowed..3: leaf defaults in the undeclaredunifi_settingsections and the deprecated optional-onlyassisted_roaming_*leaves ofunifi_devicetripped the plan-change gate of the framework..4: Terraform core plans an optional and computed object from the configuration, which is null, when the prior object holds a non-null leaf the schema does not mark computed.country.codewasRequired.
The procedure that found the last two causes is in docs/operations/terraform-provider-fork.md,
section “Find what trips a plan”. Phase 4 is pull request #3148, whose plan shows No changes. Fork
issue #24 is closed. Fork issue #20 keeps the minimum data rate fields and the fixed mesh parent:
upstream covers the roaming assistant, and the fork covers rrm_enabled, but neither has
minrate_*_data_rate_kbps.