Declarative configuration for my UniFi network, managed as
native Kubernetes resources with
Crossplane and the
provider-upjet-unifi
provider.
This is one home network's desired-state configuration, not a general-purpose UniFi tool. Start with a local render; changing the live network requires the separately managed platform and authorized controller access.
You need Git and kubectl with its built-in Kustomize command. No UniFi controller,
credentials or running cluster are needed for this check. From a directory where you
want a source checkout:
git clone https://github.com/devantler-tech/unifi.git
cd unifi
kubectl kustomize deploySuccess is a zero exit status and eight rendered resources: one Client, one
TrafficRoute and six Records, each carrying the annotation
crossplane.io/paused: "true". The render builds the checked-in manifest set. It does
not apply anything, contact the controller or prove that the live network matches.
CI also checks every field against the provider's own schema with
crossplane resource validate, for
the provider release the Platform pins. To run that check locally, render the manifests to a file
outside the repository and pass it to the script with the Crossplane CLI. It needs network access,
plus curl and yq (v4); CROSSPLANE_IMAGE is the Crossplane version CI pins in
ci.yaml:
kubectl kustomize deploy > "${TMPDIR:-/tmp}/unifi-manifests.yaml"
CROSSPLANE_IMAGE=xpkg.crossplane.io/crossplane/crossplane:v2.4.3 \
bash scripts/validate-crossplane-schemas.sh "$(command -v crossplane)" "${TMPDIR:-/tmp}/unifi-manifests.yaml"Expect Total 8 resources: 0 missing schemas, 8 success cases, 0 failure cases. A misspelled
field, a wrong value type, a missing required field or a kind no schema covers makes the check fail.
Every resource in this repository is held with crossplane.io/paused: "true", set
once in deploy/kustomization.yaml. While a resource is paused,
Crossplane does not create, change or delete anything on the controller for it.
The pause is deliberate. The resources still contain placeholders (the VPN peer
address, the VPN network id and the internal address the admin DNS records point at)
that can be filled in only once the platform's WireGuard server exists. Applying them
earlier would fail the VPN client and point the admin hostnames at an address that
does not answer. The comment in deploy/kustomization.yaml records when the pause may be
lifted. Removing the annotation is a reviewed change to the live network, never a
documentation or onboarding step.
This repository is the desired state of the network (the WireGuard VPN client,
traffic routes, local DNS records, …), expressed as Crossplane Managed Resources
(Client, TrafficRoute, Record, …). There is no Terraform and no separate state
store: the Managed Resource is the state, with its observed status in
.status.atProvider.
this repo: deploy/ (Crossplane MRs)
│ release v1.2.3 → signed artifact oci://ghcr.io/devantler-tech/unifi/manifests
│ Flux OCIRepository (newest stable release) + Kustomization → namespace: unifi
▼
provider-upjet-unifi (Crossplane, crossplane-system) ──► UniFi Controller API
Every merge to main with a feat or fix commit cuts a release
(release.yaml). Each release tag publishes deploy/,
keylessly signed by this repository's own cd.yaml on that tag.
The platform accepts only that signature,
follows the newest stable release and applies it into the unifi namespace within minutes,
with no platform change. There provider-upjet-unifi reconciles each resource that is not
paused against the UniFi controller API. A released change to deploy/ is therefore a change
to the live network. Until the platform switches its source to the artifact, it still reads
this repository at one commit it pins and verifies.
Never let the first reconcile create or destroy live network config. A Managed Resource whose external object already exists must adopt it, not create a duplicate. To bring an existing object under management:
- Write the Managed Resource to match what already exists on the controller.
- Add the annotation
crossplane.io/external-name: <unifi-id>so Crossplane binds to the live object instead of creating a new one. - (Optional, safest) start it read-only: annotate it
platform.devantler.tech/unifi-management: observe-onlyand setspec.managementPolicies: ["Observe"], so the first reconcile only reads the object; confirm.status.atProvidermatches, then remove both to manage it. The Platform honours the annotation and replaces any declaredmanagementPolicies, so the annotation is what keeps it read-only.
For a genuinely new object the network does not have yet (like everything shipped here today), no annotation is needed — Crossplane creates it. See the runbook for the step-by-step procedure and how to find a live object's id.
API-key auth (UniFi Controller ≥ 9.0.108). Use a dedicated service account with a
Limited Admin, Local Access Only role. This repo is public and holds no
secrets: the controller credentials live in the platform's secret store
(OpenBao) and are surfaced to Crossplane as a ProviderConfig whose secretRef
points at a Secret produced by an External Secret — never commit them here.
| Credential | Meaning |
|---|---|
api_url |
Controller base URL, without the /api path |
api_key |
API key (sensitive) |
site |
Site to manage (default default) |
allow_insecure |
Skip TLS verify — only for a self-signed cert |
The WireGuard VPN client additionally references two keys from a Secret in the
unifi namespace (cluster-wireguard): the gateway's own private key
(sensitive) and the Talos server's public key. Both are seeded by the
platform; see the runbook.
Follow CONTRIBUTING.md for a safe first change, the local checks and how to submit. The CI workflow renders the manifests, runs the structural check above and scans the documentation for links to retired repositories; passing it is not validation against the live network.
This repo is the steady-state Crossplane model (it replaced an interim
OpenTofu + tofu-controller setup). Next steps are tracked in the
monorepo issues — e.g. a
cross-resource reference so a TrafficRoute can point at a Client by name
instead of a post-create network id, and bringing more of the network
(VLANs/WLANs/firewall) under management adopt-first.