# 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

1. **Create VLANs** in UniFi Network → Settings → Networks
2. **Assign ports** on the switch to VLAN 10 for NUC connections
3. **Create DHCP reservations** for each NUC (Settings → Networks → VLAN 10)
4. **Add port forwarding rules** (Settings → Firewall & Security → Port Forwarding)
5. **Configure firewall rules** (Settings → Firewall & Security → Firewall Rules)
6. **Set local DNS** entries for *.homelab.local