rblundon/homelab
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated technical tdp

Browse Source
This commit is contained in:
Ryan Blundon
2026-03-07 17:50:08 -06:00
parent e3b3401544
commit 7d7129632f
2 changed files with 372 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/decisions/.gitkeep
View File

372
docs/decisions/Homelab_Technical_Decision_Points.md Normal file
View File

@@ -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`) |