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

20 KiB
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 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:

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

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:

---
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:

<group_name>:
  hosts:
    <hostname>:
      ansible_host: <ip_address>
      ansible_become: true

Step 6: Add secrets to vault

ansible-vault edit ansible/group_vars/all/vault

Add any application-specific secrets (API tokens, database passwords, etc.).

Step 7: Run the Ansible playbook

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:

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

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