Terraform Provider Fork (UniFi)
The UniFi Terraform provider this repository uses is our own fork, published to the HCP
Terraform private registry. Upstream is
ubiquiti-community/terraform-provider-unifi.
Fixes land in the fork first and go upstream as pull requests in parallel.
Where things live
Section titled “Where things live”| What | Where |
|---|---|
| Fork | fzymgc-house/terraform-provider-unifi, default branch fzymgc (the upstream base plus our commits). main mirrors upstream. |
| Release configuration | .goreleaser.fzymgc.yml in the fork: linux_arm64 (HCP agents) and darwin_arm64 (workstations) |
| Upload script | scripts/publish-hcp-registry.sh in the fork |
| go-unifi fork | fzymgc-house/go-unifi, branch fzymgc: upstream main plus our commits. The models are regenerated from the version the site runs (Regenerate the models), and the generator injects the keys the controller stores that the field specification does not list. The provider fork consumes it through a replace in go.mod, which keeps the module path github.com/ubiquiti-community/go-unifi. |
| Registry entry and signing key | tf/hcp-terraform/registry.tf (tfe_registry_provider.unifi, tfe_registry_gpg_key.provider_signing) |
| Signing key material | Vault secret/fzymgc-house/infrastructure/terraform-registry/signing-key (secrets) |
| Source address | app.terraform.io/fzymgc-house/unifi |
| Consumer | tf/unifi/versions.tf, which pins the exact version |
Consume it
Section titled “Consume it”terraform { required_providers { unifi = { source = "app.terraform.io/fzymgc-house/unifi" version = "= 0.60.0-fzymgc.5" } }}-
Versions are
<next-upstream-minor>-fzymgc.<n>. A semver pre-release never matches a range constraint, so pin the exact version. -
Renovate does not look up this provider, because it has no credential for the private registry. After a release, move the pin in
tf/unifi/versions.tfby hand. -
HCP agent-pool runs install org-private providers without extra credentials. A workstation needs
terraform loginfirst. -
Lock both platforms, or the arm64 agents fail verification on a lock file written from a Mac:
Terminal window terraform providers lock -platform=linux_arm64 -platform=darwin_arm64
Release a version
Section titled “Release a version”Prerequisites: goreleaser, gpg, jq, an authenticated vault CLI, and an HCP token that can
manage the private registry (terraform login stores one in ~/.terraform.d/credentials.tfrc.json).
-
Commit the change on
fzymgcand push an annotated tag, for examplev0.56.0-fzymgc.5. In go-unifi, tag the commit that thereplaceline ofgo.modnames asprovider-<version>, for exampleprovider-0.56.0-fzymgc.5. A squash merge leaves a branch commit offfzymgc, and only a tag keeps it reachable after the branch is deleted. The name is not semver, so Go never reads it as a module version. -
Build from the tag without signing:
Terminal window git worktree add --detach ../release v0.56.0-fzymgc.5 && cd ../releasegoreleaser release --clean --skip=publish,announce,sign --config .goreleaser.fzymgc.yml -
Sign
SHA256SUMSwith the key from Vault in a throwaway keyring. On macOS,GNUPGHOMEmust be a short path, because thegpg-agentsocket path is limited to about 104 bytes:Terminal window P=secret/fzymgc-house/infrastructure/terraform-registry/signing-keyexport GNUPGHOME=$(mktemp -d /tmp/gk.XXXX)vault kv get -field=private_key $P | gpg --batch --pinentry-mode loopback --passphrase-fd 3 --import 3< <(vault kv get -field=passphrase $P)gpg --batch --pinentry-mode loopback --passphrase-fd 3 --local-user "$(vault kv get -field=fingerprint $P)" \--detach-sign dist/terraform-provider-unifi_0.56.0-fzymgc.5_SHA256SUMS 3< <(vault kv get -field=passphrase $P)gpgconf --kill gpg-agent && rm -rf "$GNUPGHOME" -
Upload with
scripts/publish-hcp-registry.shfrom the provider repository.KEY_IDis the registry key id of the signing key: the last 16 characters of the fingerprint in the Vault entry, andterraform output provider_signing_key_idintf/hcp-terraformafter an init there. The script is idempotent. Run it again after a partial failure. Vault 2.x prints a field with no trailing newline, so the command removes any newline before it takes the last 16 characters.Terminal window KEY_ID=$(vault kv get -field=fingerprint $P | tr -d '\n' | tail -c 16)[ "${#KEY_ID}" -eq 16 ] || echo "KEY_ID is not 16 characters: $KEY_ID"TFE_TOKEN=$(jq -r '.credentials["app.terraform.io"].token' ~/.terraform.d/credentials.tfrc.json) \scripts/publish-hcp-registry.sh ../release/dist 0.56.0-fzymgc.5 "$KEY_ID" -
Verify as a consumer.
terraform initmust report(self-signed, key ID <KEY_ID>), notunauthenticated.
If a version has the wrong key id, terraform init cannot find its key. The script leaves an
existing version alone, so a second run cannot fix it. Delete the version with
DELETE /api/v2/organizations/fzymgc-house/registry-providers/private/fzymgc-house/unifi/versions/<version>,
then run the script again.
Signing key
Section titled “Signing key”The key is RSA-4096, sign-only, with no expiry. Versions stay in the registry, and an expired key
would put their verification at risk. To rotate, register a new key in tf/hcp-terraform and sign
new releases with it. Keep the old key registered while any version signed by it is in use. The
revocation certificate is in the same Vault entry.
Regenerate the models
Section titled “Regenerate the models”The generator in cmd/fields of go-unifi reads the api/fields JSON definitions of one Network
version and writes the Go models. Up to Network 10.6, it downloaded the Debian package of the
version and took the definitions out of a jar:
go run ./cmd/fields -output-dir unifi 10.6.106Network 11 ships no Debian package and no jar. The application is one native-image binary, and the definitions sit inside it as pretty-printed JSON, with their file names stored elsewhere. Copy the binary off the console as root, then give it to the generator with the version before it as the reference. The generator downloads the reference package, carves each definition out of the binary, and names it after the reference file whose top-level keys it shares the most:
scp root@192.168.40.1:/usr/lib/unifi/lib/unifi /tmp/unifi-11.0.89go run ./cmd/fields -output-dir unifi -native-image /tmp/unifi-11.0.89 -reference-version 10.6.106 11.0.89The generator prints a definition it cannot name, and a reference file that no definition
matches, which it carries forward. The custom overrides in cmd/fields/custom and the split of
Setting.json apply as before. The fields directory cmd/fields/v<version> is a cache that Git
ignores. Delete it to carve again after a change to the overrides.
The definitions do not list every key the controller stores. After a regeneration, run the field
audit of UniFi against a fresh dump, and add a key
it names to cmd/fields/main.go. For a network, add it to each encoder in
unifi/network_encode.go too.
Keep up with upstream
Section titled “Keep up with upstream”Both forks sit on upstream main plus a short series of our own commits. To move to a newer
upstream, replay the series rather than rebase it:
- In each repository, cut
fzymgc-nextfromupstream/main. - Re-apply our commits one by one. Drop a commit that upstream now covers. In go-unifi, keep every
injected key in
cmd/fields/main.goorcmd/fields/custom/*.json, then regenerate from the version the site runs (Regenerate the models). - Gate go-unifi with the field audit:
scripts/unifi-field-audit.py <dump> --go-unifi <checkout> --tier allmust printno gapfor every collection intf/unifi. - Gate the provider with
go test ./...and the acceptance suite against the demo controller. - Reset
fzymgcto the reviewed series with a force push. The old release tags keep the old commits reachable. - Release a new
<next-upstream-minor>-fzymgc.1, then move the pin intf/unifiand rewrite the configuration for any schema change upstream made. Themain-cluster-unifiplan must showNo changesbefore the pull request merges.
The rebase of 2026-10-16 is the worked example: docs/engineering/plans/2026-10-16-unifi-fork-rebase.md.
Find what trips a plan
Section titled “Find what trips a plan”A plan that updates a resource with no visible change is the plan-change gate of the provider
framework. The framework compares the planned state with the prior state before it plans
computed attributes. If the two differ anywhere, every computed attribute that the configuration
leaves out and that has no UseStateForUnknown modifier becomes (known after apply). The run
log of HCP Terraform does not show which attribute differed. A local plan of the one resource does:
- Build the fork into the directory that
dev_overridesin a CLI configuration file points at. - Fetch the plan of the HCP run as JSON from
/api/v2/plans/<plan-id>/json-output. Copy thebeforeobject of the resource fromresource_changesinto a local state file. Copy thesensitive_valuespaths intosensitive_attributestoo, because a change in sensitive marks alone makes Terraform plan an update. - Copy the resource block into a module of its own. Replace references with the literal ids.
- Run
terraform plan -refresh=falsewithTF_LOG=DEBUGand the read-only credential fromscripts/unifi-readonly.sh. The framework logsDetected value change between proposed new state and prior statewith the attribute path.
Two causes found this way, both fixed in the fork. A leaf Default fires even when the
configuration leaves the parent section out, so a default that differs from the controller trips
the gate. Terraform core plans an optional and computed object from the configuration, which is
null, when the prior object holds a non-null leaf that the schema does not mark computed, so a
Required leaf below a computed object trips the gate on every site that fills it.