Welcome to my home infrastructure and Kubernetes cluster repository! This project embraces Infrastructure as Code (IaC) and GitOps principles, leveraging Kubernetes, Flux, Renovate, and GitHub Actions to maintain a fully automated, declarative homelab environment.
My semi hyper-converged cluster runs Talos Linux—an immutable, minimal Linux distribution purpose-built for Kubernetes—on three bare-metal MS-A2 workstations. Storage is handled by Rook, providing persistent block, object, and file storage directly within the cluster, complemented by a dedicated NAS for media files. The entire cluster is architected for complete reproducibility: I can tear it down and rebuild from scratch without losing any data.
Want to build something similar? Check out the onedr0p/cluster-template to get started with these practices.
- actions-runner-controller: Self-hosted GitHub runners for CI/CD workflows.
- cert-manager: Automated SSL certificate management and provisioning.
- cilium: High-performance container networking powered by eBPF.
- cloudflared: Secure tunnel providing Cloudflare-protected access to cluster services.
- envoy-gateway: Modern ingress controller for cluster traffic management.
- external-dns: Automated DNS record synchronization for ingress resources.
- external-secrets: Kubernetes secrets management integrated with 1Password Connect.
- multus: Multi-homed pod networking for advanced network configurations.
- rook: Cloud-native distributed storage orchestrator for persistent storage.
- spegel: Stateless cluster-local OCI registry mirror for improved performance.
- volsync: Advanced backup and recovery solution for persistent volume claims.
Flux continuously monitors the kubernetes folder and reconciles my cluster state with whatever is defined in this Git repository—Git is the single source of truth.
Here's how it works: Flux recursively scans the kubernetes/apps directory, discovering the top-level kustomization.yaml in each subdirectory. These files typically define a namespace and one or more Flux Kustomization resources (ks.yaml). Each Flux Kustomization then manages a HelmRelease or other Kubernetes resources for that application.
Meanwhile, Renovate continuously scans the entire repository for dependency updates, automatically opening pull requests when new versions are available. Once merged, Flux picks up the changes and updates the cluster automatically.
This Git repository contains the following directories under kubernetes.
📁 kubernetes # Kubernetes cluster defined as code
├─📁 apps # Apps deployed into my cluster grouped by namespace (see below)
├─📁 components # Re-usable kustomize components
└─📁 flux # Flux system configurationHere's how Flux orchestrates application deployments with dependencies. Most applications are deployed as HelmRelease resources that depend on other HelmRelease's, while some Kustomization's depend on other Kustomization's. Occasionally, an application may have dependencies on both types. The diagram below illustrates this: atuin won't deploy or upgrade until rook-ceph-cluster is successfully installed and healthy.
Click to see a high-level architecture diagram
graph LR
classDef kustom fill:#43A047,stroke:#2E7D32,stroke-width:3px,color:#fff,font-weight:bold,rx:10,ry:10
classDef helm fill:#1976D2,stroke:#0D47A1,stroke-width:3px,color:#fff,font-weight:bold,rx:10,ry:10
A["📦 Kustomization<br/>rook-ceph"]:::kustom
B["📦 Kustomization<br/>rook-ceph-cluster"]:::kustom
C["🎯 HelmRelease<br/>rook-ceph"]:::helm
D["🎯 HelmRelease<br/>rook-ceph-cluster"]:::helm
E["📦 Kustomization<br/>atuin"]:::kustom
F["🎯 HelmRelease<br/>atuin"]:::helm
A -->|Creates| C
B -->|Creates| D
B -.->|Depends on| A
E -->|Creates| F
E -.->|Depends on| B
My network is built on a multi-tier architecture with enterprise-grade performance. At the core, a UniFi Dream Machine Beast handles routing and firewall duties, connected upstream to RCN's 5Gbps WAN and downstream to both a 25G aggregation switch and a 24-port PoE+ access switch. The aggregation switch forms the backbone, connecting to the NAS via 25G LACP and the three-node Kubernetes cluster via 10G LACP. The access switch serves wired end devices and wireless clients.
Click to see a high-level network diagram
graph LR
%% Class Definitions
classDef wan fill:#f87171,stroke:#fff,stroke-width:2px,color:#fff,font-weight:bold;
classDef core fill:#60a5fa,stroke:#fff,stroke-width:2px,color:#fff,font-weight:bold;
classDef agg fill:#34d399,stroke:#fff,stroke-width:2px,color:#fff,font-weight:bold;
classDef switch fill:#a78bfa,stroke:#fff,stroke-width:2px,color:#fff,font-weight:bold;
classDef device fill:#facc15,stroke:#fff,stroke-width:2px,color:#000,font-weight:bold;
classDef vlan fill:#1f2937,stroke:#fff,stroke-width:1px,color:#fff,font-size:12px;
%% Nodes
RCN[🛜 RCN<br/>5Gbps WAN]:::wan
UDM[📦 UDM Beast]:::core
AGG[🔗 Pro Aggregation XG]:::agg
NAS[💾 NAS]:::device
K8s[☸️ Kubernetes<br/>3 Nodes]:::device
SW[🔌 Pro XG 24 PoE]:::switch
DEV[💻 Devices]:::device
WIFI[📶 WiFi Clients]:::device
%% Subgraph for VLANs
subgraph VLANs [LAN +vlan]
direction TB
LOCAL[LOCAL<br/>192.168.0.0/24]:::vlan
TRUSTED[TRUSTED*<br/>192.168.1.0/24]:::vlan
SERVERS[SERVERS*<br/>192.168.10.0/24]:::vlan
SERVICES[SERVICES*<br/>192.168.20.0/24]:::vlan
IOT[IOT*<br/>192.168.30.0/24]:::vlan
GUEST[GUEST*<br/>192.168.40.0/24]:::vlan
end
style VLANs fill:#111,stroke:#fff,stroke-width:2px,rx:0,ry:0,padding:20px;
%% Links
SERVERS -.-> RCN
RCN -.->|WAN| UDM
UDM -- 25G --- AGG
UDM -- 25G --- SW
AGG -- 10G LACP --> K8s
AGG -- 25G LACP --> NAS
SW --> DEV
SW --> WIFI
%% Keep SERVERS->RCN as a hidden layout constraint and style bonded links thicker
linkStyle 0 stroke:transparent,stroke-width:0px,color:transparent;
linkStyle 2 stroke-width:4px;
linkStyle 3 stroke-width:4px;
linkStyle 4 stroke-width:2px;
linkStyle 5 stroke-width:4px;
I run two instances of ExternalDNS to handle DNS automation:
- Private DNS: Syncs records to my UDM Pro Max via the ExternalDNS webhook provider for UniFi
- Public DNS: Syncs records to Cloudflare for external services
This is achieved by defining routes with two specific gateways: internal for private DNS and external for public DNS. Each ExternalDNS instance watches for routes using its assigned gateway and syncs the appropriate DNS records to the corresponding platform.
Click to see my rack
| Device | Count | OS Disk | Data Disk | RAM | OS | Purpose |
|---|---|---|---|---|---|---|
| Minisforum MS-A2 | 3 | 1.92TB M.2 | 3.84TB U.2 + 1.92TB M.2 | 96GB | Talos | Kubernetes |
| 45HomeLab HL15 2.0 | 1 | 1.92TB M.2 | 12×22TB HDD + 2x7.68TB U.2 | 512GB | TrueNAS SCALE | NFS + Backup Storage |
| JetKVM | 3 | - | - | - | - | KVM for Kubernetes |
| UniFi Dream Machine Beast | 1 | - | 2×960GB SSD | - | UniFi OS | Router & NVR |
| UniFi Pro XG Aggregation | 1 | - | - | - | UniFi OS | 25G SFP28 Switch |
| UniFi Pro XG 24 PoE | 1 | - | - | - | UniFi OS | 10G PoE+ Switch |
| UniFi Power Distribution Pro | 1 | - | - | - | UniFi OS | PDU |
| APC SMT1500RM2UNC UPS | 1 | - | - | - | - | UPS |
Each MS-A2 (AMD Ryzen™ 9 9955HX) workstation is equipped with:
- Crucial 96GB Kit (48GBx2) DDR5-5600 SODIMM
- Samsung 1.92TB M.2 22x110mm PM9A3 NVMe PCIe 4.0
- Samsung 3.84TB U.2 PM9A3 NVMe PCIe 4.0
- Google Coral M.2 Accelerator A+E Key
Huge thanks to @onedr0p and the amazing Home Operations Discord community for their knowledge and support. If you're looking for inspiration, check out kubesearch.dev to discover how others are deploying applications in their homelabs.
See LICENSE.
