home-network-k3s-impl/apps/vms/unifi/30-virtualmachine.yaml

---
# 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.${BASE_DOMAIN}
              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" ]