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
2.7 KiB
2.7 KiB
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