rblundon/homelab
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0fb593a31302b978e6c0545cf0dea7de088d7692
homelab/docs/decisions/Homelab_Technical_Decision_Points.md

498 lines
20 KiB
Markdown
Raw Blame History

# 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 → `guest-relations` (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 |
| `guest-relations` | `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** | `guest-relations` | 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.
#### **5\.1 Provisioning a New VM (Bootstrap Mode)**
This procedure is for provisioning Tier 1 VMs before the automated pipeline (NetBox → n8n → Terraform) is available. All commands are run from `city-hall`.
**Prerequisites:** Ansible CLI, Terraform CLI, Boilerplates CLI, GitHub CLI (`gh`)
**Step 1: Create the Terraform tfvars file**
Create a new file at `terraform/proxmox/hosts/tfvars/<hostname>.tfvars`:
```hcl
hostname = "<hostname>"
vm_id = <third_octet * 1000 + fourth_octet>
ip_address = "<ip_address>"
target_node = "<proxmox_node>"
template_name = "ubuntu-24.04-<size>"
# Bootstrap mode
started = true
use_dhcp = false
```
**Step 2: Apply Terraform**
```bash
cd terraform/proxmox/hosts
terraform apply \
-var-file="tfvars/<hostname>.tfvars" \
-state="states/<hostname>.tfstate" \
-var="proxmox_api_url=https://main-street-usa.local.mk-labs.cloud:8006" \
-var="proxmox_api_token=terraform@pve!automation=<token>"
```
**Step 3: Create DNS record**
On `monorail` (Technitium), create an A record:
- `<hostname>.local.mk-labs.cloud` → `<ip_address>`
If the service has a separate service name (e.g., `authentik.local.mk-labs.cloud`), create an additional A record or CNAME pointing to `lightning-lane` (`10.1.71.35`), **not** the VM itself. All services behind Traefik must resolve to Traefik's IP.
**Step 4: Create Ansible host_vars**
Create `ansible/host_vars/<hostname>/vars`:
```yaml
---
ip_address: <ip_address>
app_role: <role>
app_name: <application>
app_deployment: docker_compose
```
**Step 5: Add to Ansible inventory**
Add the host to `ansible/inventory.yml` under the appropriate group:
```yaml
<group_name>:
hosts:
<hostname>:
ansible_host: <ip_address>
ansible_become: true
```
**Step 6: Add secrets to vault**
```bash
ansible-vault edit ansible/group_vars/all/vault
```
Add any application-specific secrets (API tokens, database passwords, etc.).
**Step 7: Run the Ansible playbook**
```bash
cd ansible
ansible-playbook -i inventory.yml playbooks/deploy_<application>.yml
```
This runs three roles in sequence: `common` (base OS) → `docker-host` (Docker CE) → `<application>` (Compose stack).
#### **5\.2 Adding a Service to Traefik**
To route a new service through `lightning-lane` (Traefik), add a dynamic configuration file and update DNS.
**Step 1: Create a dynamic config file**
Create a new YAML file at `boilerplates/traefik/dynamic/<service>.yml`:
```yaml
http:
routers:
<service>:
rule: "Host(`<service>.local.mk-labs.cloud`)"
entryPoints:
- websecure
service: <service>
tls:
certResolver: cloudflare
middlewares:
- security-headers
services:
<service>:
loadBalancer:
servers:
- url: "http://<backend_ip>:<port>"
```
To protect the service with Authentik SSO, add `authentik-forwardauth` to the middlewares list.
**Step 2: Create DNS record**
On `monorail`, create an A record pointing to **lightning-lane** (`10.1.71.35`):
- `<service>.local.mk-labs.cloud` → `10.1.71.35`
**Step 3: Deploy the configuration**
```bash
cd ansible
ansible-playbook -i inventory.yml playbooks/update_traefik_routes.yml
```
Traefik watches the dynamic configuration directory and picks up changes automatically — no restart required.
### **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** | `guest-relations` | Authentik (`10.1.71.40`) |
Reference in New Issue View Git Blame Copy Permalink