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 PRs in parallel.

Where things live

What	Where
Fork	fzymgc-house/terraform-provider-unifi, default branch fzymgc (upstream base plus our commits); main mirrors upstream
Release config	.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: the provider’s pinned go-unifi commit plus an exported ApiClient.Do for raw requests. 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 (see secrets)
Source address	app.terraform.io/fzymgc-house/unifi

Consuming it

terraform {
  required_providers {
    unifi = {
      source  = "app.terraform.io/fzymgc-house/unifi"
      version = "= 0.56.0-fzymgc.2"
    }
  }
}

• Versions are <next-upstream-minor>-fzymgc.<n>. A semver pre-release never matches a range constraint, so pin the exact version.

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

  terraform providers lock -platform=linux_arm64 -platform=darwin_arm64

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

1. Commit the change on fzymgc and push an annotated tag, e.g. v0.56.0-fzymgc.2.

2. Build from the tag without signing:

   git worktree add --detach ../release v0.56.0-fzymgc.2 && 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 (the gpg-agent socket overflows the ~104-byte Unix-socket limit otherwise):

   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.2_SHA256SUMS 3< <(vault kv get -field=passphrase $P)
   gpgconf --kill gpg-agent && rm -rf "$GNUPGHOME"

4. Upload. KEY_ID is terraform output provider_signing_key_id in tf/hcp-terraform. The script is idempotent; re-run it after a partial failure.

   TFE_TOKEN=... scripts/publish-hcp-registry.sh dist 0.56.0-fzymgc.2 7B381B811D6398AD

5. Verify as a consumer: terraform init must report (self-signed, key ID 7B381B811D6398AD), not unauthenticated.

Signing key

RSA-4096, sign-only, 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.

Keeping up with upstream

The fork is based on upstream c16b66a, the last upstream main commit that compiles: from 48ea492 on, upstream main builds against a go-unifi release missing fields the provider uses. When upstream builds again, rebase fzymgc onto it, drop any commit upstream has merged, and release a new -fzymgc.<n>.