woodhead.tech homelab infrastructure

01Design Goals

02Compute & Virtualization

Cluster Topology

Five Proxmox VE 8.x nodes on a flat Layer 2 network (192.168.86.0/24), managed as a single cluster with shared corosync quorum and a distributed Ceph storage pool.

Workload Types

LXC containers are the primary unit of service isolation. Proxmox LXC uses Linux namespaces and cgroups with no hardware virtualization overhead, making them lighter than full VMs while still providing strong isolation. Most services — Traefik, Authentik, monitoring, the ARR stack — run as LXC containers.

Full VMs are used only where bare-metal isolation is required: TrueNAS (kernel-level ZFS and raw disk passthrough), Home Assistant OS (USB device passthrough for Zigbee), and Talos Kubernetes nodes (immutable OS that manages its own kernel).

Docker Compose inside LXC is used for multi-container services (ARR stack, Authentik, monitoring, Mailcow). This avoids nested VM overhead while preserving Docker's inter-container networking model.

Resource Allocation Philosophy

CFS CPU weight scheduling (cpuunits) expresses priority under contention. Traefik (weight 2048) gets twice the CPU time of the ARR stack (weight 1024) at saturation. When cores are idle, weights are irrelevant.

VMs support memory ballooning — the hypervisor reclaims idle RAM down to a guaranteed floor. LXC containers are hard-limited by cgroups. The ThinkCentre nodes run at roughly 2–3× CPU overcommit and 2× RAM overcommit, which works in practice because most services idle the majority of the time.

03Storage Architecture

Storage is segmented into three tiers with distinct purpose and failure modes.

04Networking & Traffic Flow

All nodes connect to a flat 192.168.86.0/24 LAN via a managed switch behind a Google Nest WiFi Pro router. The Nest handles NAT, DHCP, DNS forwarding, and hairpin NAT. VLAN segmentation is deferred until VLAN-aware APs replace the Nest — the design is structured so VLANs can be added without touching service configs.

External Traffic Path

Two DNS records are intentionally not proxied through Cloudflare's CDN:

• *.woodhead.tech — DNS-only so Traefik terminates TLS and receives the client's real IP for logging.
• wg.woodhead.tech — DNS-only; Cloudflare's proxy infrastructure does not forward UDP, which WireGuard requires.

The apex domain woodhead.tech and www.woodhead.tech are proxied — they point to Cloudflare Pages (this site), not the homelab.

TLS Certificates

Traefik obtains a wildcard certificate (*.woodhead.tech) from Let's Encrypt via DNS-01 challenge. The flow: Traefik creates a _acme-challenge TXT record via the Cloudflare API → Let's Encrypt validates against public resolvers → certificate issued and stored in /etc/traefik/acme.json (mode 0600) → auto-renewed 30 days before expiry.

DNS-01 is preferred over HTTP-01 because it supports wildcard certificates and works regardless of whether ports 80/443 are currently reachable. One wildcard cert covers all subdomains at zero per-service overhead.

Internal Routing

Traefik watches /etc/traefik/dynamic/*.yml and hot-reloads on file changes — no restart required. Each file defines a router (host-matching rule + middleware chain) and a service (backend IP:port). Routes requiring authentication include the authentik@file middleware, which implements Authentik's forward-auth protocol: every request is pre-authorized against the Authentik outpost before reaching the backend.

05Security Model

WireGuard (LXC 208, 192.168.86.39) provides a VPN tunnel for remote management with split-tunnel routing — only 10.10.0.0/24 routes through the tunnel, avoiding conflicts on machines already on 192.168.86.0/24.

The ARR stack routes all download traffic through Gluetun (a WireGuard client to a commercial VPN provider). SABnzbd runs inside Gluetun's network namespace — if the VPN tunnel drops, SABnzbd loses connectivity entirely rather than leaking traffic over the plain WAN connection.

06Service Catalog

07Kubernetes Cluster

Talos Linux — an immutable, API-driven Kubernetes OS with no SSH, no shell, and no package manager. All management goes through talosctl and kubectl. This eliminates an entire class of configuration drift: there is no /etc to hand-edit, no packages to patch manually, no cron jobs to manage. An upgrade is: generate new machine configs → apply via talosctl → wait for rolling restart.

The VIP (192.168.86.100) is managed by Talos's built-in virtual IP feature — the control plane node with the lowest uptime holds it. Workers always connect to the VIP, not the control plane's physical IP.

MetalLB runs in L2 mode, advertising a pool of IPs (192.168.86.150–199) via ARP. Services of type LoadBalancer receive an IP from this pool and are directly reachable on the LAN without a separate load balancer appliance.

K8s VM disks are on the Ceph pool (3× replicated), allowing VM live migration between Proxmox nodes without unmounting storage.

08Automation Toolchain

Service group management organizes containers into dependency-aware groups (core, storage, security, media, observability, etc.). The group playbooks enforce:

• always_on groups (core, storage) refuse stop operations unconditionally.
• Dependency blocking: stopping storage while media is running fails with an error — the operator must stop dependents first.
• Hardware-bound groups (special) are excluded from bulk operations; their members must be managed individually.

09Operational Considerations

Known Failure Modes

Patching Strategy

10Roadmap

11Hardware Inventory