Skip to content

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.

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
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.tf by hand.

  • HCP agent-pool runs install org-private providers without extra credentials. A workstation needs terraform login first.

  • 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

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).

  1. Commit the change on fzymgc and push an annotated tag, for example v0.56.0-fzymgc.5. In go-unifi, tag the commit that the replace line of go.mod names as provider-<version>, for example provider-0.56.0-fzymgc.5. A squash merge leaves a branch commit off fzymgc, 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.

  2. Build from the tag without signing:

    Terminal window
    git worktree add --detach ../release v0.56.0-fzymgc.5 && cd ../release
    goreleaser release --clean --skip=publish,announce,sign --config .goreleaser.fzymgc.yml
  3. Sign SHA256SUMS with the key from Vault in a throwaway keyring. On macOS, GNUPGHOME must be a short path, because the gpg-agent socket path is limited to about 104 bytes:

    Terminal window
    P=secret/fzymgc-house/infrastructure/terraform-registry/signing-key
    export 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"
  4. Upload with scripts/publish-hcp-registry.sh from the provider repository. KEY_ID is the registry key id of the signing key: the last 16 characters of the fingerprint in the Vault entry, and terraform output provider_signing_key_id in tf/hcp-terraform after 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"
  5. Verify as a consumer. terraform init must report (self-signed, key ID <KEY_ID>), not unauthenticated.

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.

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.

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:

Terminal window
go run ./cmd/fields -output-dir unifi 10.6.106

Network 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:

Terminal window
scp root@192.168.40.1:/usr/lib/unifi/lib/unifi /tmp/unifi-11.0.89
go run ./cmd/fields -output-dir unifi -native-image /tmp/unifi-11.0.89 -reference-version 10.6.106 11.0.89

The 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.

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:

  1. In each repository, cut fzymgc-next from upstream/main.
  2. 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.go or cmd/fields/custom/*.json, then regenerate from the version the site runs (Regenerate the models).
  3. Gate go-unifi with the field audit: scripts/unifi-field-audit.py <dump> --go-unifi <checkout> --tier all must print no gap for every collection in tf/unifi.
  4. Gate the provider with go test ./... and the acceptance suite against the demo controller.
  5. Reset fzymgc to the reviewed series with a force push. The old release tags keep the old commits reachable.
  6. Release a new <next-upstream-minor>-fzymgc.1, then move the pin in tf/unifi and rewrite the configuration for any schema change upstream made. The main-cluster-unifi plan must show No changes before the pull request merges.

The rebase of 2026-10-16 is the worked example: docs/engineering/plans/2026-10-16-unifi-fork-rebase.md.

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:

  1. Build the fork into the directory that dev_overrides in a CLI configuration file points at.
  2. Fetch the plan of the HCP run as JSON from /api/v2/plans/<plan-id>/json-output. Copy the before object of the resource from resource_changes into a local state file. Copy the sensitive_values paths into sensitive_attributes too, because a change in sensitive marks alone makes Terraform plan an update.
  3. Copy the resource block into a module of its own. Replace references with the literal ids.
  4. Run terraform plan -refresh=false with TF_LOG=DEBUG and the read-only credential from scripts/unifi-readonly.sh. The framework logs Detected value change between proposed new state and prior state with 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.