Skip to content

Platform Architecture

The homelab runs on one Lenovo Legion Y540 node. Talos Linux supplies an immutable Kubernetes host, while Flux turns the main branch of this repository into the desired cluster state.

Reconciliation layers

flowchart TB
    Git[GitHub main branch] --> Source[Flux GitRepository]
    Source --> Controllers[Infrastructure controllers]
    Controllers --> Configs[Infrastructure configuration]
    Configs --> Workloads[Applications]
    Configs --> Monitoring[Monitoring layer]

The order is intentional:

  1. Flux installs operators and controllers.
  2. Configuration custom resources are applied after their controllers exist.
  3. Applications reconcile after shared infrastructure is ready.
  4. Monitoring installs after shared infrastructure, followed by ecosystem monitors after the Prometheus CRDs are healthy.

Runtime foundation

Component Current role
Talos Linux v1.13.6 Immutable operating system and Kubernetes lifecycle
Kubernetes v1.36.2 Workload scheduler and control plane
containerd 2.2.5 Container runtime
Flannel Pod networking
CoreDNS Cluster service discovery
NVIDIA GPU Operator v26.3.3 GPU discovery, validation, metrics, and device plugin
Local Path Provisioner v0.0.36 Dynamic local PersistentVolumes on the Talos NVMe filesystem
kube-prometheus-stack 87.15.2 Cluster metrics, dashboards, and alert evaluation

The initial Talos machine configuration includes the NVIDIA extensions, kernel modules, single-node scheduling policy, and NVMe volume layout. Flux owns the GPU Operator Helm release and Local Path Provisioner that expose those host capabilities to Kubernetes. The boundaries are documented on the GPU Operator and Local Path Provisioner pages.

Repository ownership

  • gitops/clusters/lab activates the reconciliation layers.
  • gitops/apps owns user-facing workloads.
  • gitops/infrastructure owns shared controllers and configuration.
  • gitops/monitoring owns the observability stack and ecosystem monitors.
  • iac/vault owns configuration inside Vault that Kubernetes cannot bootstrap.

Continue with Traffic flow, Secrets flow, the platform setup, or the repository structure.