96e3f32f28
Turborepo + pnpm monorepo for k3s homelab cluster on Intel NUCs. - Apps: Next.js web frontend, Express API (TypeScript, Dockerfiles, k8s manifests) - Packages: shared UI, ESLint config, TypeScript config, Drizzle DB schemas - Infra/Ansible: bare-metal provisioning with roles for common, k3s-server, k3s-agent, hardening - Infra/Kubernetes: ArgoCD GitOps (app-of-apps + ApplicationSets), platform components (cert-manager, Traefik, CloudNativePG, Valkey, Longhorn, Sealed Secrets), namespaces - Observability: kube-prometheus-stack, Loki, Promtail as ArgoCD Applications - CI/CD: GitHub Actions for PR builds, preview deploys, production deploys - DX: Taskfile, utility scripts, copier templates, Ubiquiti network docs
Ubiquiti Cloud Gateway Configuration
Documentation for the Ubiquiti Cloud Gateway (UCG) that manages network ingress for the homelab cluster.
Network Layout
Internet
│
▼
UCG (Ubiquiti Cloud Gateway)
│
├── VLAN 1 - Management (10.0.1.0/24)
├── VLAN 10 - Servers (10.0.10.0/24)
├── VLAN 20 - IoT (10.0.20.0/24)
└── VLAN 99 - Guest (10.0.99.0/24)
VLAN Configuration
| VLAN ID | Name | Subnet | Purpose |
|---|---|---|---|
| 1 | Management | 10.0.1.0/24 | Network devices, admin |
| 10 | Servers | 10.0.10.0/24 | k3s cluster nodes |
| 20 | IoT | 10.0.20.0/24 | IoT devices |
| 99 | Guest | 10.0.99.0/24 | Guest WiFi |
DHCP Reservations (VLAN 10 — Servers)
| Hostname | IP Address | MAC Address | Role |
|---|---|---|---|
| nuc01 | 10.0.10.11 | XX:XX:XX:XX:XX:01 | k3s server |
| nuc02 | 10.0.10.12 | XX:XX:XX:XX:XX:02 | k3s agent |
| nuc03 | 10.0.10.13 | XX:XX:XX:XX:XX:03 | k3s agent |
Port Forwarding Rules
| Name | External Port | Internal IP | Internal Port | Protocol |
|---|---|---|---|---|
| HTTP | 80 | 10.0.10.11 | 80 | TCP |
| HTTPS | 443 | 10.0.10.11 | 443 | TCP |
| k3s API | 6443 | 10.0.10.11 | 6443 | TCP |
Note
: HTTP/HTTPS traffic routes to nuc01 where Traefik runs as the ingress controller. k3s API port is only forwarded if external kubectl access is needed.
Firewall Rules
Inter-VLAN Rules
- Servers → Internet: Allow all outbound
- Servers → Management: Allow (for UCG API access)
- IoT → Servers: Deny (isolate IoT from cluster)
- **Guest → ***: Allow Internet only, block all local
Inbound Rules
- Allow established/related connections
- Allow HTTP (80) and HTTPS (443) to VLAN 10
- Drop all other inbound
DNS Configuration
- Internal DNS: Use UCG as DNS server for VLAN 10
- External DNS: Cloudflare (1.1.1.1, 1.0.0.1)
- Local DNS entries: Add
*.homelab.local→ 10.0.10.11 for internal access
Setup Steps
- Create VLANs in UniFi Network → Settings → Networks
- Assign ports on the switch to VLAN 10 for NUC connections
- Create DHCP reservations for each NUC (Settings → Networks → VLAN 10)
- Add port forwarding rules (Settings → Firewall & Security → Port Forwarding)
- Configure firewall rules (Settings → Firewall & Security → Firewall Rules)
- Set local DNS entries for *.homelab.local