--- # KubeVirt VirtualMachine — the self-hosted UniFi OS Server (UOS) controller. # # WHY A VM (PM directive): the classic `unifi` .deb is deprecated. UOS is Ubiquiti's current # self-host product — a single installer that runs on Ubuntu Server and bundles UniFi OS + the # Network application + its OWN embedded datastore inside a Podman container stack. NO separate # MongoDB companion is needed. # # DELIVERY: this VM is NOT on the app "wave" track — it is reconciled by the non-gating `apps-vms` # Flux Kustomization (clusters/base/apps-vms.yaml, wait:false) so the slow first-boot image import # + UOS install can't stall the app waves. UniFi has no in-cluster dependents. # # LIVE MIGRATION: evictionStrategy: LiveMigrate + the RWX (longhorn-vm) root disk let the VM # drain to another node without downtime (node maintenance / rebalancing). # # LABELS on the pod template (propagated to the virt-launcher pod): # - kubevirt.io/vm: unifi -> Service/CNP selector target # - app.kubernetes.io/name: unifi -> convention # - egress-class: internet -> Cilium egress steering (default WAN path) # - auth-mode: native -> UniFi has its OWN login UI (no Keycloak/oauth2-proxy in # front of it). REQUIRED by Kyverno require-auth-mode-label # for any pod in an app-namespace. apiVersion: kubevirt.io/v1 kind: VirtualMachine metadata: name: unifi namespace: unifi labels: app.kubernetes.io/name: unifi spec: running: true template: metadata: labels: kubevirt.io/vm: unifi app.kubernetes.io/name: unifi homelab.keithjackson.dev/egress-class: internet homelab.keithjackson.dev/auth-mode: native spec: # LiveMigrate on eviction — needs the RWX migratable disk (longhorn-vm). Without a shared # disk KubeVirt cannot migrate and eviction would hard-stop the guest. evictionStrategy: LiveMigrate domain: # FLAG (verify-at-bringup): Ubuntu 24.04 amd64 cloud images are hybrid BIOS+UEFI bootable, # so KubeVirt's default SeaBIOS SHOULD boot cleanly (unlike the Fedora containerdisk, which # is UEFI-only and needed an explicit efi block). If the guest drops to emergency/no-boot, # add: firmware: { bootloader: { efi: { secureBoot: false } } } cpu: cores: 2 memory: guest: 4Gi # UOS min is 2Gi; 4Gi is comfortable for a home site. Bump to 8Gi # for large device counts / heavy DPI. Keep guest == requests below. devices: disks: - name: rootdisk disk: bus: virtio - name: cloudinit disk: bus: virtio interfaces: - name: default masquerade: {} # Declaring ports on a masquerade iface (a) restricts pod->VM forwarding to exactly # these and (b) surfaces them as containerPorts on the virt-launcher pod so the # LoadBalancer Services + CiliumNetworkPolicy ingress can target/match them. ports: - { name: inform, port: 8080, protocol: TCP } # device inform / adoption - { name: ui-legacy, port: 8443, protocol: TCP } # legacy Network UI (still served) - { name: ui, port: 11443, protocol: TCP } # UOS web UI (modern default) - { name: portal-http, port: 8880, protocol: TCP } # guest portal HTTP - { name: portal-https, port: 8843, protocol: TCP } # guest portal HTTPS - { name: throughput, port: 6789, protocol: TCP } # mobile speedtest / throughput - { name: stun, port: 3478, protocol: UDP } # STUN (device<->controller) - { name: discovery, port: 10001, protocol: UDP } # L2 device discovery resources: requests: memory: 4Gi networks: - name: default pod: {} volumes: - name: rootdisk dataVolume: name: unifi-rootdisk - name: cloudinit cloudInitNoCloud: # INLINE (kept < KubeVirt's 2048-byte userData limit — so NO SSH key here; add one back via # userDataSecretRef only if needed). qemu-guest-agent gives the KubeVirt AgentConnected # signal (proves cloud-init ran); install-uos resolves the latest UOS linux-x64 build from # Ubiquiti's PUBLIC firmware API (no auth) and installs it non-interactively (UI on :11443). # NOTE: apps-vms NOW carries postBuild.substituteFrom cluster-vars (needed for # ${UNIFI_L4_VIP} in 50-service-l4.yaml), so Flux envsubst DOES run over this userData. # Every shell brace-expansion below is therefore escaped as $${...}, which envsubst emits # as a literal $${...} — verified with `flux envsubst`. Bare $VAR and $(...) are left alone # by envsubst and need no escaping. NEVER write an unescaped $${...} here, and never write # an INDEXED expansion unescaped: envsubst hard-fails on `[` ("missing closing brace") # and would break the whole apps-vms apply. CORRECTION (2026-09-01, measured against # flux 2.4.0 `envsubst --strict`): escaping IS total — $${ARR[0]} emits the literal # text safely. Only the UNESCAPED indexed form is fatal. The earlier "escaped or not" # wording in clusters/base/apps-vms.yaml overstated it. userData: |- #cloud-config hostname: unifi fqdn: unifi.home.keithjackson.dev package_update: true package_upgrade: false packages: [qemu-guest-agent, podman, uidmap, slirp4netns, ca-certificates, curl, jq, cloud-guest-utils] write_files: - path: /usr/local/sbin/install-uos permissions: '0755' content: | #!/usr/bin/env bash set -euo pipefail if [ -z "$${UOS_URL:-}" ]; then UOS_URL="$(curl -fsSL https://fw-update.ui.com/api/firmware-latest | jq -r '._embedded.firmware|map(select(.product=="unifi-os-server" and .platform=="linux-x64"))|sort_by(.version_major,.version_minor,.version_patch)|last._links.data.href')" fi [ -n "$${UOS_URL}" ] && [ "$${UOS_URL}" != "null" ] || { echo "no UOS URL"; exit 1; } t="$(mktemp)"; echo "downloading $${UOS_URL}"; curl -fL --retry 5 --retry-delay 10 -o "$t" "$UOS_URL"; chmod +x "$t"; echo "installing"; yes | "$t"; echo "done" runcmd: - [ systemctl, enable, --now, qemu-guest-agent ] - [ systemctl, enable, --now, podman.socket ] - [ bash, -lc, "/usr/local/sbin/install-uos 2>&1 | tee /var/log/uos-install.log > /dev/console" ]