System architecture overview
A concise map of the homelab stack: hypervisor to apps: so you always know what runs where.
About the system architecture
This design marries an immutable Talos OS, Kubernetes, and GitOps to create a repeatable, auditable platform for self-managed services.
info
Why you care: Understanding the layers helps you troubleshoot faster and extend the platform safely.
Key layers in more detail
| Layer | What it does | Primary tool |
|---|---|---|
| Hypervisor | Hosts all VMs | Proxmox VE |
| Node OS | Minimal, API-managed Linux | Talos |
| Networking | eBPF CNI + policies | Cilium |
| Traffic routing | L4/L7 gateways | Gateway API |
| State sync | Declarative config | ArgoCD + Kustomize |
| Workloads | Apps + infra | Helm charts / YAML |
Prerequisites
- Basic Kubernetes familiarity.
- Access to the repo for cross-referenced manifests.
Overview of data flow
- Git commit → ArgoCD reconciles to cluster.
- Cilium eBPF → handles service routing.
- Gateway API → exposes traffic internally/externally.
Dive deeper
- Provisioning flow: Talos with OpenTofu
- Configuration flow: Manage Kubernetes with GitOps
- Application strategy: Deploy and manage applications
Verify the architecture in your cluster
kubectl get nodes -o wide # Talos nodes present?
argocd app list # All apps Synced/Healthy?