🏡 homelab

Talos Linux homelab managed with FluxCD, Kustomize, and Helm

A self-hosted Kubernetes lab built for clean GitOps workflows, shared platform services, and a small but intentional app layer.

⚙️ The repository is the source of truth for the cluster resources managed by Flux.

🧰 Stack Overview

Layer	Tooling
Kubernetes	Talos Linux
GitOps	FluxCD
Packaging	Helm + Kustomize
Networking	MetalLB + Traefik
Secrets	Vault + External Secrets Operator
Public access	Cloudflare Tunnel
Hardware	NVIDIA GPU Operator
Apps	Homepage + Linkding + Postiz
Documentation	Zensical in docs/

📁 Repository Structure

.
├── gitops/                 # Flux-managed Kubernetes manifests
│   ├── apps/              # User-facing workloads
│   ├── infrastructure/    # Shared platform capabilities
│   ├── monitoring/        # Observability layer
│   └── clusters/          # Flux entrypoints for the lab cluster
├── iac/                   # Terraform configuration for Vault
└── docs/                  # Documentation site

✅ base/ holds reusable service definitions.

🧪 lab/ holds homelab-specific overlays.

🎛️ gitops/clusters/ decides what Flux actually reconciles.

🏗️ iac/vault/ manages configuration inside Vault that Kubernetes manifests do not own.

🚀 Current State

Active now

Layer	Active services
Apps	homepage, linkding, postiz
Infrastructure	metallb, traefik, vault, external-secrets, cloudflared, local-path-provisioner, gpu-operator, cnpg
Monitoring	Prometheus, Alertmanager, Grafana, Metrics Server, node-exporter, kube-state-metrics

Grafana and Prometheus are available on the local network at http://grafana.homelab.internal and http://prometheus.homelab.internal. Alertmanager remains internal to the cluster.

🧭 How It Flows

1. Manifests live in gitops/apps/, gitops/infrastructure/, and gitops/monitoring/.
2. base/ defines the reusable service shape.
3. lab/ adds homelab-specific values, ingress, storage, and overlays.
4. gitops/clusters/lab/*.yaml tells Flux what to reconcile and in what order.

📚 Documentation

• docs/index.md shows the current architecture
• docs/architecture/ explains relationships that span multiple services
• docs/gitops/ explains repository structure, reconciliation, and service wiring
• docs/apps/ documents user-facing applications
• docs/services/ documents individual services and dependencies
• docs/runbooks/ contains repeatable setup, operations, and recovery procedures

🧠 Philosophy

• Keep the cluster declarative.
• Separate apps from shared infrastructure.
• Activate services explicitly through the cluster entrypoints.
• Keep monitoring as its own concern.
• Make the repo easier to understand before making it more powerful.