# Snarfnet Homelab Topology Reference

This document maps out the subnets, host IP assignments, cluster contexts, and service exposures across the **snarfnet** homelab.

---

## 1. Network VLAN & Subnet Mapping

| VLAN ID | Name | Subnet | Primary Usage |
|---|---|---|---|
| **1** | LAN | `14.44.4.0/25` | UDM Pro gateway (`14.44.4.1`), core switches. |
| **2** | Management | `140.44.44.0/24` | APs, USP RPS, Octofarm, iDRAC, MeshCentral. |
| **3** | Spacedock | `140.44.1.0/24` | Isolated virtual lab workloads. |
| **20** | Compute | `140.44.4.0/25` | All three Kubernetes clusters, Swarm/Portainer VMs. |
| **30** | Media | `192.168.1.0/25` | Smart TVs, Roku, media players. |
| **40** | Storage | `14.10.10.0/25` | SnarfNAS (`14.10.10.72`), SN-NAS (`14.10.10.71`). |
| **50** | Smart Home | `14.4.4.0/25` | Home Assistant (`14.4.4.20`), NUT Master Server (`14.4.4.44`), Nest Hubs, LIFX Bulbs. |
| **60** | HA | `140.4.4.0/25` | High-availability clustering interfaces. |

---

## 2. Kubernetes & Harvester Cluster Layouts

All Kubernetes resources are hosted on the **Compute VLAN (VLAN 20 — `140.44.4.0/25`)**.

### Cluster A: `aerodrome` (Local / Rancher Management Cluster)
*   **Infrastructure role:** Hosts Rancher management plane, Authentik SSO, Grafana, AWX, and Uptime Kuma.
*   **SSH Default User:** `root`
*   **IP Allocation:**
    *   `sninfr2lnxctl01` $\rightarrow$ `140.44.4.11` (Master Node, Debian 12, Ready)
    *   `sninfr2lnxctl02` $\rightarrow$ `140.44.4.12` (Master Node, Debian 12, Ready)
    *   `sninfr2lnxctl03` $\rightarrow$ `140.44.4.13` (Master Node, Debian 12, Ready)
    *   `sninfr2lnxwrk01` $\rightarrow$ `140.44.4.21` (Worker Node, Debian 12, Ready)
    *   `sninfr2lnxwrk02` $\rightarrow$ `140.44.4.22` (Worker Node, Debian 12, Ready)
    *   `sninfr2lnxwrk03` $\rightarrow$ `140.44.4.23` (Worker Node, Debian 12, Ready)
    *   `sninfr2lnxwrk04` $\rightarrow$ `140.44.4.24` (Worker Node, Debian 12, Ready)
    *   `sninfr2lnxwrk05` $\rightarrow$ `140.44.4.25` (Worker Node, Debian 12, Ready)
    *   `sninfr2lnxwrk06` $\rightarrow$ `140.44.4.26` (Worker Node, Debian 12, Ready)
    *   `sninfr2lnxwrk07` $\rightarrow$ `140.44.4.27` (Worker Node, Debian 12, Ready)
*   **MetalLB IP Range:** `140.44.4.28` - `140.44.4.39`
    *   `140.44.4.28` $\rightarrow$ `monitoring/uptime-lb`
    *   `140.44.4.29` $\rightarrow$ `infra/authentik-lb`
    *   `140.44.4.30` $\rightarrow$ `awx/awx-lb`
    *   `140.44.4.31` $\rightarrow$ `infra/technitium-npm-vip-service`
    *   `140.44.4.32` $\rightarrow$ `default/grafana-lb`
    *   `140.44.4.33` $\rightarrow$ `infra/unified-npm-vip-service`
    *   `140.44.4.34` $\rightarrow$ `kube-system/traefik` (Unified Ingress endpoint)


---

### Cluster B: `spacedock` (Harvester HCI Virtualization Cluster)
*   **Infrastructure role:** Physical hypervisors running Harvester v1.8.0. Handles virtual machine provisioning and GPU partition workloads.
*   **SSH Default User:** `rancher`
*   **IP Allocation:**
    *   `snaihvs0lnx01` $\rightarrow$ `140.44.4.81` (Master/HCI, amd64, Ready)
    *   `snaihvs0lnx02` $\rightarrow$ `140.44.4.82` (Master/HCI, amd64, Ready)
    *   `snaihvs0lnx03` $\rightarrow$ `140.44.4.83` (Master/HCI, amd64, Ready)

---

### Cluster C: `spaceport` (Raspberry Pi Downstream Cluster)
*   **Infrastructure role:** Hosts development and operational workloads: Gitea, Homepage, Jenkins, Semaphore (Ansible), Coder, and your primary Zabbix monitoring server.
*   **SSH Default User:** `root` (Dropbear SSH on DietPi/Debian 12; password `dietpi` on `ctl01-04` & `wrk01-04, 06`, `Katzir476!` on `wrk05`)
*   **IP Allocation:**
    *   `sninfr0lnxctl01` $\rightarrow$ `140.44.4.41` (Master Node, arm64 RPi 5, Ready)
    *   `sninfr0lnxctl02` $\rightarrow$ `140.44.4.42` (Master Node, arm64 RPi 5, Ready)
    *   `sninfr0lnxctl03` $\rightarrow$ `140.44.4.43` (Master Node, arm64 RPi 5, Ready)
    *   `sninfr0lnxctl04` $\rightarrow$ `140.44.4.44` (Master Node, arm64 RPi 5, Ready)
    *   `sninfr0lnxwrk01` $\rightarrow$ `140.44.4.51` (Worker Node, arm64 RPi 5, Ready)
    *   `sninfr0lnxwrk02` $\rightarrow$ `140.44.4.52` (Worker Node, arm64 RPi 5, Ready)
    *   `sninfr0lnxwrk03` $\rightarrow$ `140.44.4.53` (Worker Node, arm64 RPi 5, Ready)
    *   `sninfr0lnxwrk04` $\rightarrow$ `140.44.4.54` (Worker Node, arm64 RPi 5, Ready)
    *   `sninfr0lnxwrk05` $\rightarrow$ `140.44.4.55` (Worker Node, arm64 RPi 5, Ready)
    *   `sninfr0lnxwrk06` $\rightarrow$ `140.44.4.56` (Worker Node, arm64 RPi 5, Ready)
*   **MetalLB IP Range:** `140.44.4.57` - `140.44.4.65`
    *   `140.44.4.57` $\rightarrow$ `monitoring/zabbix-zabbix-web` (Port 8888)
    *   `140.44.4.58` $\rightarrow$ `infrastructure/semaphore-lb` (Port 100)
    *   `140.44.4.59` $\rightarrow$ `infrastructure/jenkins-lb` (Port 101)
    *   `140.44.4.60` $\rightarrow$ `infrastructure/homepage-lb` (Port 8040)
    *   `140.44.4.61` $\rightarrow$ `monitoring/zabbix-zabbix-server` (Ports 10051/10052)
    *   `140.44.4.62` $\rightarrow$ `infrastructure/gitea-lb` (Port 90)
    *   `140.44.4.63` $\rightarrow$ `infrastructure/coder` (Port 96)
    *   `140.44.4.64` $\rightarrow$ `kube-system/traefik` (Ingress endpoint, Ports 80/443)
    *   `140.44.4.65` $\rightarrow$ `infrastructure/pihole-web` (Port 80 - *Currently stuck pending*)

---

### Cluster D: `shipyard` (Docker Swarm / Portainer Legacy Cluster)
*   **Infrastructure role:** Hosts legacy containerized stacks (Nginx Proxy Manager, Gotify, Heimdall dashboard, Homebox inventory, MeshCentral remote management, Peanut, Pi-hole, VS Code Server, and Watchtower).
*   **SSH Default User:** `snarf`
*   **IP Allocation:**
    *   `Shipyard VIP` $\rightarrow$ `140.44.4.70` (Keepalived Virtual IP)
    *   `Shipyard 01` $\rightarrow$ `140.44.4.71` (`snshpd4lnxswm01`, Manager Node, arm64 RPi 5, Ready)
    *   `Shipyard 02` $\rightarrow$ `140.44.4.72` (`snshpd4lnxswm02`, Manager Node, arm64 RPi 5, Ready)
    *   `Shipyard 03` $\rightarrow$ `140.44.4.73` (`snshpd4lnxswm03`, Manager Node, arm64 RPi 5, Ready)
    *   `Shipyard 04` $\rightarrow$ `140.44.4.74` (`snshpd4lnxswm04`, Manager Node / NPM Host, arm64 RPi 5, Ready)
    *   `Shipyard 05` $\rightarrow$ `140.44.4.75` (`snshpd4lnxswm05`, Manager Node, arm64 RPi 5, Ready)

---

### AI Stack (Raspberry Pis)
*   **Infrastructure role:** Edge AI inference and local web interface.
*   **SSH Default User:** `snarf`
*   **IP Allocation:**
    *   `snnpud4lnxops01` $\rightarrow$ `140.44.4.7` (Raspberry Pi with AI Hat 2, arm64, Ready)
    *   `snnpud4lnxweb01` $\rightarrow$ `140.44.4.8` (Raspberry Pi running Open WebUI, arm64, Ready)

---

## 3. Core Edge Port Forwardings (UDM Pro Gateway)

External WAN traffic hitting `174.106.252.96` is forwarded to internal hosts as follows:

1.  **Nginx Reverse Proxy:** Ports `80` & `443` forward to **`140.44.4.74`** (`snshpd4lnxswm04` in Docker Swarm).
    *   *Real Client IP Preservation:* NPM runs with `mode: host` (`PublishMode: host`) pinned to `snshpd4lnxswm04`. This eliminates Docker Swarm overlay ingress SNAT (which previously masked all clients as `10.0.0.6`), ensuring `X-Forwarded-For` and `X-Real-IP` preserve the true WAN or LAN client IP.
    *   *Conditional Authentik MFA:* Authentik's `default-authentication-flow-authenticator-validate-stage` evaluates the real client IP. Connections from internal subnets (`14.4.4.0/24`, `14.44.4.0/24`, `140.44.4.0/24`, `14.10.10.0/24`) bypass MFA for frictionless homelab usage, while external WAN connections strictly enforce MFA.
2.  **Dev Machine/Gaming:** Ports `8443`, `10823` & `27015-27050` forward to **`14.4.4.15`** (Desktop PC).
3.  **Zabbix Trapper:** Ports `10051` & `10052` forward to **`140.44.4.51`** (Klipper ServiceLB on worker `sninfr0lnxwrk01` $\rightarrow$ routes to primary Zabbix server pod in `spaceport`).

---

## 4. Subdomain Ingress Map (Nginx Proxy Manager)

This table records how subdomains on `*.snarfnet.net` route to internal IP addresses and ports through the NPM instance at `140.44.4.74`:

| Domain Name | Protocol | Target IP / VIP | Port | Internal Service |
|---|---|---|---|---|
| `*.snarfnet.net` | HTTP | `140.44.4.70` (Swarm VIP) | 85 | Staged Wildcard / Landing portal |
| `portal.snarfnet.net` | HTTP | `140.44.4.70` (Swarm VIP) | 85 | Heimdall Dashboard |
| `nginx.snarfnet.net` | HTTP | `140.44.4.70` (Swarm VIP) | 81 | NPM Admin Web Console |
| `gotify.snarfnet.net` | HTTP | `140.44.4.70` (Swarm VIP) | 8090 | Gotify Notification Server |
| `mesh.snarfnet.net` | HTTPS | `140.44.4.70` (Swarm VIP) | 8086 | MeshCentral Remote Manager |
| `peanut.snarfnet.net` | HTTP | `140.44.4.70` (Swarm VIP) | 8050 | Peanut Dashboard |
| `homebox.snarfnet.net` | HTTP | `140.44.4.70` (Swarm VIP) | 3100 | Homebox Inventory Tracker |
| `pihole.snarfnet.net` | HTTP | `140.44.4.70` (Swarm VIP) | 8041 | Legacy Swarm Pi-hole 1 |
| `pihole2.snarfnet.net` | HTTP | `140.44.4.70` (Swarm VIP) | 8042 | Legacy Swarm Pi-hole 2 |
| `shipyard.snarfnet.net` | HTTPS | `140.44.4.71` (Swarm 01) | 9443 | Portainer Server Console |
| `shipyardcontrol.snarfnet.net` | HTTPS | `140.44.4.7` (AI Node) | 443 | Turing Pi Management / Hardware Panel |
| `ai.snarfnet.net` | HTTP | `140.44.4.8` (AI Web Node) | 8080 | Open WebUI Inference Interface |
| `aerodrome.snarfnet.net` | HTTPS | `140.44.4.34` (K3s VIP) | 443 | Rancher Management Console |
| `grafana.snarfnet.net` | HTTP | `140.44.4.32` (K3s VIP) | 88 | Grafana Monitoring Dashboards |
| `authentik.snarfnet.net` | HTTPS | `140.44.4.29` (K3s VIP) | 444 | Authentik SSO Portal |
| `uptime.snarfnet.net` | HTTP | `140.44.4.28` (K3s VIP) | 448 | Uptime Kuma Status Dashboard |
| `awx.snarfnet.net` | HTTPS | `140.44.4.30` (K3s VIP) | 443 | AWX Operator Web UI |
| `argo.snarfnet.net` | HTTP | `140.44.4.51` (K3s Node) | 80 | ArgoCD GitOps (routes via Spaceport Traefik) |
| `git.snarfnet.net` | HTTP | `140.44.4.51` (K3s Node) | 90 | Gitea Repository Server |
| `coder.snarfnet.net` | HTTP | `140.44.4.51` (K3s Node) | 96 | Coder Dev Environment Portal |
| `zabbix.snarfnet.net` | HTTP | `140.44.4.51` (K3s Node) | 8888 | Zabbix Web UI Console |
| `homepage.snarfnet.net` | HTTP | `140.44.4.41` (K3s Node) | 8040 | Spaceport Homepage Portal |
| `semaphore.snarfnet.net` | HTTP | `140.44.4.41` (K3s Node) | 100 | Semaphore Ansible Web Console |
| `jenkins.snarfnet.net` | HTTP | `140.44.4.52` (K3s Node) | 101 | Jenkins Automation Server |
| `plex.snarfnet.net` | HTTP | `14.10.10.71` (NAS 1) | 32400 | Plex Media Server |
| `kavita.snarfnet.net` | HTTPS | `14.10.10.71` (NAS 1) | 5471 | Kavita Ebook Reader |
| `sn-nas.snarfnet.net` | HTTPS | `14.10.10.71` (NAS 1) | 5001 | SN-NAS DSM Administration |
| `snarfnas.snarfnet.net` | HTTPS | `14.10.10.72` (NAS 2) | 5001 | SnarfNAS DSM Administration |
| `lights.snarfnet.net` | HTTP | `14.4.4.90` (WLED Node) | 80 | WLED Office Lighting Controller |
| `octoprint2.snarfnet.net` | HTTP | `14.44.4.14` (Printer Node) | 80 | OctoPrint 3D Printer Console |
| `harvester.spacedock.snarfnet.net`| HTTPS | `140.44.4.90` | 443 | Harvester Console interface |
| `spacedock1.snarfnet.net` | HTTPS | `140.44.44.121` | 80 | Harvester Hypervisor Node 1 UI |
| `spacedock3.snarfnet.net` | HTTPS | `140.44.44.123` | 80 | Harvester Hypervisor Node 3 UI |
| `spacedock4.snarfnet.net` | HTTP | `140.44.44.124` | 80 | Dakboard Display Node |
| `longhorn.aerodrome.snarfnet.net`| HTTP | `140.44.4.36` (K3s VIP) | 80 | Longhorn Storage UI (Aerodrome) |
| `longhorn.spaceport.snarfnet.net` | HTTP | `140.44.4.41` (K3s Node) | 80 | Longhorn Storage UI (Spaceport) |