Homelab Kubernetes Platform

This wiki documents the planned architecture, build decisions, and migration path for the homelab's transition from mostly standalone Docker and TrueNAS-hosted services to an RKE2 Kubernetes cluster with UDS Core.

Current status — 2026-09-16: Actual Budget remains in production. GitchAlerts is now owner-confirmed deployed to production; run 64 passed signed bundle 0.1.6 deployment, rollouts and HTTPS health using automatically issued credentials. See GitchAlerts Migration and Homelab Operations Status. Remaining production-edge IaC reconciliation and reusable TLS onboarding are tracked in platform#45.

Updated architecture diagram — 2026-10-08: PostgreSQL on TrueNAS outside Kubernetes; Pi-hole retained for LAN DNS and ad blocking. The diagram distinguishes recorded deployments from planned transitions.

Documentation scope

Environment-specific: Homelab Operations Status, Mat's migration plan, node inventory and operational addresses describe this homelab only.
Reusable guidance: Application Delivery Automation explains the general pattern using placeholders. Values and one-writer migration decisions must be adapted elsewhere.
Older planning pages describe intent, not deployment evidence. Dated owner-confirmed findings on the status page take precedence over older status summaries. Credentials and private keys never belong in the wiki.

Start here

RKE2 Control Plane Setup — reusable control-plane installation and WSL administration runbook
RKE2 Worker Setup — reusable worker installation and validation runbook
MetalLB Layer 2 Load Balancing — reusable service-address, installation, validation, and operations runbook
TrueNAS CSI Storage Integration — dynamic NFS and iSCSI provisioning runbook
UDS Core Prerequisites and Readiness — compatibility decisions, prerequisite status, and deployment gate
UDS Application Delivery and Repository Architecture — Forgejo repository ownership, UDS bundle delivery, CI/CD, and secrets model
Final Architecture — updated diagram and system boundaries
Node Roles — hardware, placement intent, labels, taints, and affinity
Storage Strategy — TrueNAS, dynamic provisioning, static NFS, and local PVs
Migration Roadmap — phased build and reversible application migration
Security and Secrets — public-repository handling rules
Homelab Roadmap — shared organization board; issues remain in their owning operational repositories
Platform ingress issue — current tracker for the former public issue 20
Mat's application migration plan — current workload placement and migration sequence

Design principles

Build the platform before migrating applications. Networking and storage must be stable before UDS Core or production workloads depend on them.
Migrate incrementally. Existing Docker services continue running until each workload has an approved, validated, reversible cutover.
Keep data where it makes sense. Existing TrueNAS datasets remain in place. ComfyUI assets remain node-local on the media GPU worker, while suitable game-server data may move to TrueNAS for scheduling across the Sager and OptiPlex.
Keep foundational dependencies outside Kubernetes initially. The LAN DNS service, AIStor, external PostgreSQL, Forgejo, and the Windows runner remain outside Kubernetes so foundational services do not depend on cluster health. Forgejo may still share hardware with the control-plane node.
Avoid premature implementation decisions. MetalLB Layer 2 is selected for application LoadBalancer Services. A future control-plane API VIP remains a separate decision, while versions, certificate details, and environment-specific values remain placeholders until selected and documented.
Treat the repository as public. No credentials, kubeconfigs, private keys, real Kubernetes Secret values, or credential-bearing environment files may be committed.

Planned progression

Established: RKE2 / MetalLB / TrueNAS storage / UDS Core / Istio
Accepted: Actual Budget production; GitchAlerts production deployment (2026-09-16)
Remaining: reusable production-edge provisioning and IaC reconciliation (platform#45)
Ongoing: certificate renewal verification and migration of additional apps

Planning pages describe the target state, while completed runbooks document the current build. The owning issues on Homelab Roadmap remain the source of truth for implementation status. The public repository is for documentation and sanitized examples; operational configuration belongs in Homelab/platform or the relevant application repository. See Security and Secrets before handling any bootstrap artifacts.

Homelab Wiki