k8s-homelab

A production-grade Kubernetes homelab built on Talos Linux and managed entirely through GitOps. The goal is to mirror real-world platform engineering practices — infrastructure as code, automated secret management, automated dependency updates, and full observability — at home scale.

---

Architecture Overview

                        Internet
                            |
                    Cloudflare Tunnel
                            |
                     Envoy Gateway
                    (Gateway API)
                     /          \
              Ingress-NGINX    HTTPRoutes
                     |              |
              Internal apps   External backends
                              (Proxmox, TrueNAS)

The cluster runs on Proxmox VMs provisioned with Talos Linux (immutable, API-driven OS). All cluster state lives in this Git repository and is reconciled continuously by ArgoCD.

---

Cluster

Property	Value
OS	Talos Linux v1.12.3
Kubernetes	v1.34.0
Topology	3 control planes + 4 workers
CNI	Cilium (VXLAN tunnel mode)
GitOps	ArgoCD (app-of-apps pattern)

Workers run Talos extensions for iSCSI support (iscsi-tools, util-linux-tools) and a QEMU guest agent, enabling Longhorn distributed storage.

---

Key Design Decisions

Talos Linux — chosen for its immutable, minimal, API-driven design. No SSH, no package manager, no shell on nodes. All configuration is declarative YAML applied via talosctl. Secrets are encrypted at rest with SOPS.

Cilium in tunnel mode — VXLAN encapsulation avoids the need to configure BGP or L2 routes in the home network, keeping the underlay simple while still getting eBPF-based networking.

App-of-apps with ArgoCD — a root Application points to k8s-0/applications/, which contains individual Application manifests split into system/ and apps/. This gives a clear separation between platform components and user-facing workloads, with independent sync policies per layer.

Envoy Gateway (Gateway API) over Ingress — the Kubernetes Gateway API is the future standard for traffic management. Envoy Gateway handles all external routing, while Ingress-NGINX remains available for workloads that still rely on Ingress resources.

Cloudflare Tunnel — no ports are exposed on the home router. All external traffic enters via a Cloudflare Tunnel, which also provides DDoS protection, access policies, and automatic TLS termination at the edge.

External Secrets + Bitwarden — secrets never live in Git. External Secrets Operator syncs secrets from a self-hosted Vaultwarden instance into the cluster at runtime using the Bitwarden CLI as a webhook backend. Three ClusterSecretStore types cover logins, custom fields, and secure notes.

Longhorn — distributed block storage across all worker nodes with dedicated disks. Talos worker nodes are pre-labeled to opt into Longhorn disk discovery automatically at provision time.

CloudNative-PG — PostgreSQL managed as a Kubernetes-native operator, with the barman-cloud plugin for S3-compatible backups. Used by Nextcloud, Gatus, and Strapi.

---

Stack

Platform / Infrastructure

Component	Role
Talos Linux	Immutable Kubernetes OS
ArgoCD	GitOps continuous delivery
Cilium	CNI (eBPF networking)
MetalLB	Bare-metal LoadBalancer
Envoy Gateway	Kubernetes Gateway API
Ingress-NGINX	Ingress controller
Cloudflared	Zero-trust tunnel (no open ports)
External-DNS	Automatic DNS record sync to Cloudflare
cert-manager	Automated TLS via Let's Encrypt
Longhorn	Distributed persistent block storage
External Secrets Operator	Secret sync from Vaultwarden
CloudNative-PG	PostgreSQL operator with backup support
Redis	In-cluster cache
Renovate	Automated dependency/chart version updates

Observability

Component	Role
kube-prometheus-stack	Prometheus + Grafana + alerting
Gatus	Uptime and health endpoint monitoring

Custom Grafana dashboards are included for: ArgoCD, CloudNative-PG, Proxmox, and TrueNAS. Gatus endpoint configs are injected dynamically via a k8s-sidecar watching labeled ConfigMaps.

Applications

Application	Stack
Nextcloud	File sync/share — PostgreSQL + Redis + Longhorn
pgAdmin	PostgreSQL web management UI
Strapi	Headless CMS — PostgreSQL backend
Superset	Data visualization / BI

---

Secret Management Flow

Vaultwarden (self-hosted)
        |
  Bitwarden CLI (webhook)
        |
  External Secrets Operator
        |
  Kubernetes Secrets (runtime only, never in Git)

Secrets are referenced in manifests as ExternalSecret resources that pull from named items in Vaultwarden. Three ClusterSecretStore types handle different Bitwarden item structures (logins, custom fields, secure notes).

---

Repository Structure

k8s-0/
  0-cluster-setup/
    talos/              # Talos machine configs (talconfig.yaml, SOPS-encrypted secrets)
  applications/
    system/             # ArgoCD Applications for platform components
    apps/               # ArgoCD Applications for user-facing workloads
  argocd/               # ArgoCD Helm values + root app
  cert-manager/         # cert-manager + ClusterIssuer
  cilium/               # Cilium CNI values
  cloudflared/          # Cloudflare Tunnel deployment
  cloudnative-pg/       # CloudNative-PG operator + backup plugin
  external-dns/         # External-DNS (Cloudflare provider)
  external-secrets/     # ESO + Bitwarden ClusterSecretStores
  gateway/              # Envoy Gateway + HTTPRoutes for external backends
  gatus/                # Uptime monitoring + RBAC
  ingress-nginx/        # Ingress-NGINX controller
  longhorn/             # Longhorn distributed storage
  metallb/              # MetalLB + IP pool
  nextcloud/            # Nextcloud (GitOps-managed)
  pgadmin/              # pgAdmin
  prometheus-stack/     # kube-prometheus-stack + custom dashboards
  redis/                # Redis
  renovate/             # Renovate dependency update bot
  strapi/               # Strapi CMS
  superset/             # Apache Superset

---

Tools Used

• talosctl — Talos cluster lifecycle management
• talhelper — generates per-node Talos configs from a single talconfig.yaml
• SOPS — encrypts secrets committed to Git
• kubectl / kustomize — Kubernetes resource management
• argocd CLI — ArgoCD administration
• Helm charts vendored locally via kustomize helmCharts