From 7d7129632f4e6099d889fe648d9b071ea2cd3c1c Mon Sep 17 00:00:00 2001 From: Ryan Blundon Date: Sat, 7 Mar 2026 17:50:08 -0600 Subject: [PATCH] updated technical tdp --- docs/decisions/.gitkeep | 0 .../Homelab_Technical_Decision_Points.md | 372 ++++++++++++++++++ 2 files changed, 372 insertions(+) delete mode 100644 docs/decisions/.gitkeep create mode 100644 docs/decisions/Homelab_Technical_Decision_Points.md diff --git a/docs/decisions/.gitkeep b/docs/decisions/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/decisions/Homelab_Technical_Decision_Points.md b/docs/decisions/Homelab_Technical_Decision_Points.md new file mode 100644 index 0000000..8b0dd82 --- /dev/null +++ b/docs/decisions/Homelab_Technical_Decision_Points.md @@ -0,0 +1,372 @@ +# Homelab Technical Decision Points + +## Network Hardware: + +- Ubiquiti + ++ ## Networks + + + Default + + **VAN:** 1 + + **Subnet:** 192\.168.1.0/24 + + **WiFi:** None + + Firewall Rules: + + + Main + + **VAN:** 10 + + **Subnet:** 192\.168.10.0/24 + + **WiFi:** TheInternet + + Firewall Rules: + + + Guest + + **VAN:** 3 + + **Subnet:** 192\.168.3.0/24 + + **WiFi:** BeOurGuest + + **Firewall Rules:** + + + Servers Trusted + + **VAN:** 71 + + **Subnet:** 10\.1.71.0/24 + + **WiFi:** ImaginationInstitute + + Firewall Rules: + + + Servers Untrusted + + **VAN:** 82 + + **Subnet:** 10\.1.82.0/24 + + **WiFi:** None + + Firewall Rules: + + + IoT + + **VAN:** 2 + + **Subnet:** 192\.168.2.0/24 + + **WiFi:** IoT + + Firewall Rules: + + + Cameras + + **VAN:** 9 + + **Subnet:** 192\.168.9.0/24 + + **WiFi:** Cameras + + Firewall Rules: + +## NAS: + +- Synology (`emporium`) + +## SAN: + +- Pure Storage FlashArray (`utilidor`) + ++ ## Server Hardware: + + - Minisforum MS-01 (3) + + - Minisforum H60 (3) (Overflow) + + Hypervisors: + + - Proxmox (3) + + Operating Systems + + - Linux: + + - Fedora + + - Ubuntu (Preferred) + + PXE + + - Matchbox + + Automation: + + - Ansible CLI + + - AAP + + - Terraform + + ### Need to make decisions on what to host on: + + - LXC + + - VMs + + - Kubernetes + + - Docker + + - Podman + +## Primary Infrastructure Server + +***infra01*** *(Deprecated — services have been distributed to dedicated hosts)* + +Services previously hosted here have been migrated: + +- Authoritative DNS → `monorail` (Technitium LXC) +- Identity Management → `turnstile` (Authentik VM) +- Automation (Ansible) → `imagineering` (Semaphore VM) +- Infrastructure as Code (Terraform) → `city-hall` (VM) +- iPXE (Matchbox) → TBD + + + + + + + +### **1\.0 Executive Summary** + +This document outlines the technical decisions regarding the IP address allocation and thematic naming conventions for the `mk-labs` homelab environment. The chosen theme is **Magic Kingdom at Walt Disney World**, providing a cohesive and scalable framework for all physical and virtual assets. This approach enhances organization and simplifies management. The domain for all local services will be `[local.mk-labs.cloud](local.mk-labs.cloud)`. + +### **2\.0 Networks** + +This section details the VLANs configured for the homelab environment. + +| Network Name | VLAN ID | Gateway | Subnet | DNS Server | DHCP Range | +|---|---|---|---|---|---| +| **Default** | 1 | `192.168.1.1` | `192.168.1.0/24` | Server | `192.168.1.110 - .254` | +| **Guest** | 3 | `192.168.3.1` | `192.168.3.0/24` | Server | `192.168.3.6 - .254` | +| **Server Trusted** | 71 | `10.1.71.1` | `10.1.71.0/24` | Server | `10.1.71.210 - .230` | +| **IoT** | 2 | `192.168.2.1` | `192.168.2.0/24` | Server | `192.168.2.6 - .254` | +| **Management** | 21 | `10.10.21.1` | `10.10.21.0/24` | Server | `10.10.21.200 - .254` | +| **Server Untrusted** | 250 | `192.168.250.1` | `192.168.250.0/24` | None | \- | +| **Storage** | 121 | `10.10.121.1` | `10.10.121.0/24` | Server | `10.10.121.6 - .254` | +| **Cluster** | 22 | `10.10.22.1` | `10.10.22.0/24` | None | \- | +| **Main** | 10 | `192.168.10.1` | `192.168.10.0/24` | Server | `192.168.10.6 - .254` | +| **Cameras** | 9 | `192.168.9.1` | `192.168.9.0/24` | Server | `192.168.9.6 - .254` | + +### **2\.1 Server VLAN IP Allocation Strategy** + +IP addresses within the **Server Trusted** VLAN (`10.1.71.0/24`) will be statically assigned in CIDR-aligned blocks to ensure predictability and simplify firewall rule management. + +| CIDR Block | Usable Range | Purpose | Management | +|---|---|---|---| +| **`10.1.71.0/27`** | `.1 - .30` | Core Infrastructure (Proxmox Hosts, Storage, Networking) | Static IP | +| **`10.1.71.32/27`** | `.33 - .62` | Critical Network Services (DNS, NTP, IDM, Automation) | Static IP | +| **`10.1.71.64/26`** | `.65 - .126` | Container Orchestration (Kubernetes Nodes & VIPs) | Static IP | +| **`10.1.71.128/25`** | `.129 - .254` | General Applications & VM Pool | Static IP or DHCP Reservation | + +### **3\.0 DNS Architecture** + +The DNS strategy is split between external and internal resolution. + +- **Recursive DNS (External Resolution):** Handled by the UDM Pro (`world-drive`) using DNS over HTTPS (DoH) with Cloudflare Zero Trust. No self-hosted recursive servers will be deployed. + +- **Authoritative DNS (Internal Resolution):** The `monorail` host, a Technitium DNS LXC, is the sole authoritative source for all queries for the internal `[local.mk-labs.cloud](local.mk-labs.cloud)` domain. + +- **DNS Forwarding:** A DNS forwarding record on `world-drive` directs all queries for `[local.mk-labs.cloud](local.mk-labs.cloud)` to the `monorail` host, enabling seamless internal name resolution. + +### **3\.2 Master Hostname & IP Allocation** + +This table serves as the single source of truth for all statically assigned hostnames and IP addresses within the server VLAN (`10.1.71.0/24`). + +#### Core Infrastructure (`10.1.71.0/27`) + +| Hostname | IP Address | Role / Service | Application | Hardware | Notes | +|---|---|---|---|---|---| +| `world-drive` | `10.1.71.1` | Router | Unifi 9.x | UDM Pro | Physical | +| `utilidor` | `10.1.71.5` | SAN | Pure Storage FlashArray | FlashArray | Physical | +| `utilidor-ct0` | `10.1.71.6` | SAN Controller | Pure Storage FlashArray | FlashArray | Physical | +| `utilidor-ct1` | `10.1.71.7` | SAN Controller | Pure Storage FlashArray | FlashArray | Physical | +| `emporium` | `10.1.71.9` | Network Attached Storage | Synology DSM | Synology 1621+ | Physical | +| `main-street-usa` | `10.1.71.11` | Virtualization Server | Proxmox 9.x | Minisforum TH-60 | Physical | +| `tomorrowland` | `10.1.71.12` | Virtualization Server | Proxmox 9.x | Minisforum TH-60 | Physical | +| `fantasyland` | `10.1.71.13` | Virtualization Server | Proxmox 9.x | Minisforum TH-60 | Physical | + +#### Critical Network Services (`10.1.71.32/27`) + +| Hostname | IP Address | Role / Service | Application | Hardware | Notes | +|---|---|---|---|---|---| +| `monorail` | `10.1.71.32` | Authoritative DNS | Technitium | — | LXC | +| `sundial` | `10.1.71.33` | Local Time Server | Chrony | — | LXC | +| `fire-station` | `10.1.71.34` | IPAM / Source of Truth | NetBox | — | LXC | +| `lightning-lane` | `10.1.71.35` | Reverse Proxy / Load Balancer | Traefik | — | VM (Docker Compose / Boilerplates) | +| `tiki-room` | `10.1.71.36` | Workflow Orchestration | n8n | — | VM (Docker Compose) | +| `imagineering` | `10.1.71.37` | Automation Server (Ansible) | Semaphore | — | VM | +| `city-hall` | `10.1.71.38` | Infrastructure as Code | Terraform / Boilerplates CLI | — | VM | +| `timekeeper` | `10.1.71.39` | Backup & Recovery | Proxmox Backup Server | — | VM | +| `turnstile` | `10.1.71.40` | Identity Provider / SSO | Authentik | — | VM (Docker Compose / Boilerplates) | +| `cinderella-castle` | `10.1.71.41` | Monitoring & Observability | Prometheus / Grafana | — | VM | + +#### Container Orchestration (`10.1.71.64/26`) + +| Hostname | IP Address | Role / Service | Application | Hardware | Notes | +|---|---|---|---|---|---| +| `space-mountain` | `10.1.71.65` | K8s Control Plane | TalosOS | — | VM | +| `big-thunder-mountain` | `10.1.71.66` | K8s Control Plane | TalosOS | — | VM | +| `splash-mountain` | `10.1.71.67` | K8s Control Plane | TalosOS | — | VM | +| `jungle-cruise` | `10.1.71.68` | K8s Worker (on-stage) | TalosOS | — | VM | +| `haunted-mansion` | `10.1.71.69` | K8s Worker (backstage) | TalosOS | — | VM | +| `peter-pans-flight` | `10.1.71.70` | K8s Worker (backstage) | TalosOS | — | VM | + +#### General Applications & VM Pool (`10.1.71.128/25`) + +| Hostname | IP Address | Role / Service | Application | Hardware | Notes | +|---|---|---|---|---|---| +| `be-our-guest` | `10.1.71.129` | Web Server | WordPress | — | K8s (on-stage) | +| `main-street-station` | `10.1.71.130` | Application Dashboard | TBD | — | K8s (backstage) | +| `arcade` | `10.1.71.131` | Game Server | Minecraft | — | K8s (backstage) | +| `people-mover` | `10.1.71.132` | Project Management | Plane.so | — | K8s (backstage) | + +*(This table will be populated as new services are deployed)* + +### **3\.3 Naming Standards** + +### **3\.3.1 Physical Infrastructure** + +The core physical hardware will be named after the foundational "lands" and infrastructure of the Magic Kingdom. + +| Role | Name | Description | +|---|---|---| +| **Proxmox Cluster** | `magic-kingdom` | The name for the entire Proxmox cluster, representing the whole park. | +| **Primary Proxmox Host** | `main-street-usa` | The foundational "land" and entry point, hosting critical services. | +| **Expansion Hosts** | `tomorrowland`, `fantasyland`, etc. | Additional hosts named after the other lands of the park. | +| **NAS (Synology)** | `emporium` | The Main Street shop where everything is available, representing the central NAS. | +| **SAN (Pure Storage)** | `utilidor` | The backstage service tunnels, representing the enterprise block storage system. | + +### **3\.3.2 Service & Application Naming** + +| Service Category | Name | Thematic Reason | +|---|---|---| +| **Authoritative DNS** | `monorail` | The primary, official transportation system, authoritative for all park routes. | +| **Automation Server** | `imagineering` | The engineering division that designs and builds everything in the park. | +| **Identity Provider / SSO** | `turnstile` | The authentication gate — you can't enter the Magic Kingdom without passing through it. | +| **Reverse Proxy / Load Balancer** | `lightning-lane` | The fast-track system that routes guests efficiently to their destination. | +| **Workflow Orchestration** | `tiki-room` | The enchanted show where everything is automated and orchestrated in harmony. | +| **Infrastructure as Code** | `city-hall` | The administrative headquarters where all park operations are planned and managed. | +| **IPAM / Source of Truth** | `fire-station` | The first building on Main Street, the foundational source of truth for the park. | +| **Monitoring Dashboard** | `cinderella-castle` | The central viewpoint with a line of sight to the entire homelab. | +| **Application Dashboard** | `main-street-station` | The central station and starting point to access all applications. | +| **Backup & Recovery** | `timekeeper` | The time-traveling attraction, protecting and preserving data across time. | +| **Security Services (IDS/IPS)** | `space-rangers` | An elite force protecting the network from threats. | +| **Password Manager** | `pirates-of-the-caribbean` | The attraction dedicated to protecting valuable treasure (passwords). | +| **CI/CD Platform** | `tron-lightcycle-run` | The futuristic attraction where applications are built on "the Grid." | + +### **4\.0 Storage Architecture** + +Storage for the `magic-kingdom` Proxmox cluster is provided by two systems: + +- **`emporium`** (Synology 1621+): General-purpose NAS providing NFS & iSCSI storage for VMs, LXCs, and ISOs. +- **`utilidor`** (Pure Storage FlashArray): Enterprise block storage for high-performance workloads and Kubernetes persistent volumes (via democratic-csi). + +The following LUNs have been created on `emporium` and assigned to the cluster for shared storage. + +| LUN Name | Size | Purpose | +|---|---|---| +| `mk-general` | 2T | General purpose storage for VMs, LXCs, and ISOs. | +| `mk-templates` | 1T | Dedicated storage for VM and LXC templates. | + +### **5\.0 Core Services Hosting Strategy** + +Core services are deployed using a tiered model based on their relationship to the Kubernetes cluster (`fastpass`): + +**Tier 1 — Outside Kubernetes (Proxmox LXC/VM):** +Services that Kubernetes depends on to function, or that must exist before the cluster can bootstrap. These are provisioned via Terraform + Ansible through the IaC pipeline on `city-hall`. + +- **LXC deployments:** Lightweight services with no full kernel requirements (DNS, NTP, IPAM). +- **VM deployments (Docker Compose via Boilerplates):** Services requiring a full OS, Docker runtime, or operational flexibility (automation, orchestration, identity, ingress). Docker Compose templates are generated using the [Christian Lempa Boilerplates CLI](https://github.com/ChristianLempa/boilerplates) installed on `city-hall`. + +**Tier 2 — Inside Kubernetes (ArgoCD/Helm):** +Application workloads with no circular dependency on the cluster. Managed declaratively via ArgoCD and Helm charts, deployed into `on-stage` or `backstage` zones. + +**Retired approach:** Proxmox VE Community Helper Scripts are no longer used for production deployments in favor of fully codified IaC. + +### **6\.0 Kubernetes Architecture** + +The primary Kubernetes cluster will be named `fastpass`. The name is derived from the park's system for orchestrating access to resources, which is a direct metaphor for Kubernetes' function. + +#### **6\.1 Deployment Technology Stack** + +- **Operating System: `TalosOS`** + + - **Reasoning:** TalosOS is a purpose-built, immutable Linux distribution for Kubernetes. Nodes are API-managed via `talosctl` with no SSH access, reducing attack surface and configuration drift. Machine configs define the entire node state declaratively. + +- **Deployment Pipeline:** + + - NetBox (`fire-station`) → n8n (`tiki-room`) → Terraform (`city-hall`, using Proxmox + Talos providers) → `talosctl bootstrap` → ArgoCD takes over + + - **Note:** Ansible (`imagineering`) does **not** touch Talos nodes. It is scoped exclusively to Tier 1 LXC/VM infrastructure. + +#### **6\.2 Deployment Model** + +A single-cluster model will be used for resource efficiency and to reduce management overhead. Workload isolation between internal and external-facing applications will be achieved using logical "zones" within the cluster, enforced by Kubernetes-native tools. + +- **Worker Node Zones:** Worker nodes will be separated into two thematic zones based on Disney park operational terms: + + - **`on-stage`:** This zone is for external-facing services (the "DMZ"). It represents the public areas of the park. Nodes in this zone will be tainted to prevent untrusted workloads from being scheduled on them. + + - **`backstage`:** This zone is for internal-only services. It represents the secure, operational core of the park. + +- **Workload Placement:** Pod scheduling will be controlled via **labels**, **`nodeAffinity`**, and **tolerations**. + +- **Network Security:** Traffic flow between zones and pods will be strictly controlled using **Network Policies**. + +#### **6\.3 Node Naming Convention** + +- **Control Plane Nodes:** Named after the iconic "Mountain" attractions. These are the largest, most complex, and critical rides that form the backbone of the park. + +- **Worker Nodes:** Named after other classic "E-Ticket" attractions. These are the high-capacity workhorses that run the majority of the park's experiences. + +| Role | Initial Node Names | Zone | +|---|---|---| +| **Control Plane** | `space-mountain`, `big-thunder-mountain`, `splash-mountain` | N/A | +| **Worker Node 1** | `jungle-cruise` | `on-stage` | +| **Worker Node 2** | `haunted-mansion` | `backstage` | +| **Worker Node 3** | `peter-pans-flight` | `backstage` | + +### **7\.0 Decision Summary** + +The adoption of this comprehensive thematic naming convention provides a logical, scalable, and engaging framework for the `mk-labs` homelab. It ensures that every component has a clear and memorable identity that aligns with its function. + +### **Appendix A: Additional Hostname Ideas** + +This section contains a list of pre-approved hostname ideas for future services. + +| Service Category | Recommended Name | Thematic Reason | +|---|---|---| +| **VPN Server** | `magical-express` | Securely transports you from the outside world into the private network. | +| **Ad Blocker** | `orange-bird` | A friendly service that works silently to make the user experience better. | +| **Code Server / Dev Env** | `mickeys-toontown-fair` | A creative, hands-on place for building and experimenting with code. | +| **Home Automation** | `carousel-of-progress` | The attraction that showcases the evolution of technology in the home. | +| **Game Server** | `tom-sawyer-island` | An island dedicated to adventure, exploration, and play. | +| **Recipe Manager** | `caseys-corner` | The iconic hot dog spot; a simple name for a service that manages food. | + +### **Appendix B: Assigned Hostnames (Previously in Appendix A)** + +These hostnames have been assigned to active services and are documented here for reference. + +| Service Category | Assigned Name | Assigned To | +|---|---|---| +| **NAS** | `emporium` | Synology 1621+ (`10.1.71.9`) | +| **Identity Provider / SSO** | `turnstile` | Authentik (`10.1.71.40`) | +