znibb/kobbo-homelab
1
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

feat: Add UniFi OS Server #32

New issue
Open
opened 2026-06-17 20:35:32 +00:00 by znibb · 0 comments
znibb commented 2026-06-17 20:35:32 +00:00
Owner
Copy link

Overview

Deploy UniFi OS Server — Ubiquiti's modern self-hosted platform for managing UniFi network devices (APs, switches, routers). It replaces the legacy UniFi Network Controller and bundles the Network app, Identity Hub, and Site Magic SD-WAN in one unified platform.

Running it in the cluster eliminates the need for a dedicated Cloud Key and keeps all homelab services in one place.

How it works in Kubernetes

Two options exist:

Option A — UniFi OS Server (modern, recommended)

Option B — Legacy UniFi Network Application + MongoDB

  • Older approach, still works but is being phased out.
  • Runs the Network controller backed by a MongoDB sidecar/StatefulSet.
  • PVCs for both UniFi config and MongoDB data.

Critical networking requirement

UniFi devices must be able to reach the controller on port 8080 (TCP, HTTP) for the inform/adoption URL. This is the most common failure point in containerized deployments.

  • Use a MetalLB LoadBalancer service (not Traefik HTTP ingress) so devices on the LAN can reach port 8080 directly.
  • Set the inform URL on devices to http://<metallb-ip>:8080/inform.
  • The web UI (port 8443 HTTPS) can go through Traefik.

Files to create

kubernetes/apps/unifi/
  namespace.yaml
  deployment.yaml      # UniFi OS Server pod
  service-lb.yaml      # MetalLB LoadBalancer for device ports (8080, 8443, 3478/UDP, etc.)
  pvc.yaml             # Persistent storage for config and DB
  ingressroute.yaml    # Optional: Traefik IngressRoute for web UI
  secret.enc.yaml      # SOPS-encrypted credentials if needed

Ports needed

Port Protocol Purpose
8080 TCP Device inform (required for adoption)
8443 TCP Web UI / HTTPS
3478 UDP STUN
10001 UDP Device discovery
1900 UDP L2 discovery (optional)

Considerations

  • All data must be stored in PVCs — restarts or rescheduling must not lose device config.
  • Do not put port 8080 behind Traefik — it needs a direct LoadBalancer IP.
  • If the existing Newt tunnel is in use, UniFi remote management may conflict; keep it LAN-only.

References

## Overview Deploy **UniFi OS Server** — Ubiquiti's modern self-hosted platform for managing UniFi network devices (APs, switches, routers). It replaces the legacy UniFi Network Controller and bundles the Network app, Identity Hub, and Site Magic SD-WAN in one unified platform. Running it in the cluster eliminates the need for a dedicated Cloud Key and keeps all homelab services in one place. ## How it works in Kubernetes Two options exist: ### Option A — UniFi OS Server (modern, recommended) - Ubiquiti's new unified platform. - Community Helm chart: [chrissnell/unifi-os-kubernetes](https://github.com/chrissnell/unifi-os-kubernetes) - Also: [lemker/unifi-os-server](https://github.com/lemker/unifi-os-server) ### Option B — Legacy UniFi Network Application + MongoDB - Older approach, still works but is being phased out. - Runs the Network controller backed by a MongoDB sidecar/StatefulSet. - PVCs for both UniFi config and MongoDB data. ## Critical networking requirement UniFi devices must be able to reach the controller on **port 8080 (TCP, HTTP)** for the inform/adoption URL. This is the most common failure point in containerized deployments. - Use a **MetalLB LoadBalancer** service (not Traefik HTTP ingress) so devices on the LAN can reach port 8080 directly. - Set the inform URL on devices to `http://<metallb-ip>:8080/inform`. - The web UI (port 8443 HTTPS) can go through Traefik. ## Files to create ``` kubernetes/apps/unifi/ namespace.yaml deployment.yaml # UniFi OS Server pod service-lb.yaml # MetalLB LoadBalancer for device ports (8080, 8443, 3478/UDP, etc.) pvc.yaml # Persistent storage for config and DB ingressroute.yaml # Optional: Traefik IngressRoute for web UI secret.enc.yaml # SOPS-encrypted credentials if needed ``` ## Ports needed | Port | Protocol | Purpose | |------|----------|---------| | 8080 | TCP | Device inform (required for adoption) | | 8443 | TCP | Web UI / HTTPS | | 3478 | UDP | STUN | | 10001 | UDP | Device discovery | | 1900 | UDP | L2 discovery (optional) | ## Considerations - All data must be stored in PVCs — restarts or rescheduling must not lose device config. - **Do not put port 8080 behind Traefik** — it needs a direct LoadBalancer IP. - If the existing Newt tunnel is in use, UniFi remote management may conflict; keep it LAN-only. ## References - [UniFi self-hosting docs (Ubiquiti)](https://help.ui.com/hc/en-us/articles/360012282453-Self-Hosting-a-UniFi-Network-Server) - [unifi-os-kubernetes Helm chart](https://github.com/chrissnell/unifi-os-kubernetes) - [Talos Linux guide for UniFi Controller](https://oneuptime.com/blog/post/2026-03-03-run-unifi-controller-on-talos-linux/view)
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
develop
main
app/tailscale
No results found.
Labels
Clear labels   
gitops-rework
GitOps workflow setup with Flux and local dev environment

No labels
gitops-rework
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
znibb/kobbo-homelab#32
No description provided.