Kubernetes Home Cluster

A two-node, GitOps-managed home Kubernetes cluster powered by Talos Linux, Flux CD, and TrueCharts ClusterTool.

        

  

                    

---

Overview

This repository is the source of truth for the cluster. Flux continuously reconciles Kubernetes resources from Git, while Renovate proposes chart and image updates. Secrets and cluster environment values are encrypted with SOPS and Age.

Platform

Area	Components
Operating system	Talos Linux
GitOps	Flux CD, Kustomize, Helm Controller
Networking	Cilium, Multus, Whereabouts, MetalLB, ingress-nginx
Storage and backup	Longhorn, OpenEBS, CSI snapshots, VolSync
Databases	CloudNativePG
Certificates and DNS	cert-manager, Blocky, Cloudflare DDNS
Hardware integration	Intel and generic device plugins, Node Feature Discovery
Image distribution	Spegel
Automation	Renovate, TUPPR system upgrades

Repository Structure

.
├── clusters/main/
│   ├── clusterenv.yaml              # SOPS-encrypted cluster substitutions
│   ├── talos/                       # Talos machine configuration and patches
│   └── kubernetes/
│       ├── apps/                    # General user-facing applications
│       ├── core/                    # Cluster-wide configuration services
│       ├── flux-system/             # Flux bootstrap, sources, and notifications
│       ├── kube-system/             # Kubernetes networking and node services
│       ├── media/                   # Media servers and acquisition automation
│       ├── networking/              # Internal and external ingress controllers
│       ├── observability/           # Metrics, logs, dashboards, health, and exporters
│       └── system/                  # Storage, databases, certificates, and controllers
├── repositories/                    # Helm and OCI repository definitions
└── .sops.yaml                       # SOPS encryption policy

Each managed workload follows the same pattern:

<domain>/<workload>/
├── ks.yaml                          # Flux Kustomization and Git path
└── app/
    ├── helm-release.yaml            # HelmRelease values and version
    ├── kustomization.yaml           # Workload resources
    └── namespace.yaml               # Namespace and Pod Security labels

Observability

Observability workloads live under clusters/main/kubernetes/observability.

Workload	Purpose
Alloy	Telemetry and log collection
Gatus	Endpoint and service health monitoring
Grafana	Dashboards and visualization
Headlamp	Kubernetes visibility and administration
Kromgo	Public, Prometheus-backed status badges
kube-prometheus-stack	Prometheus, Alertmanager, exporters, and alert rules
Loki	Centralized log storage and querying
TrueNAS Exporter	TrueNAS metrics collection
Unpoller	UniFi metrics collection

Media

Media workloads live under clusters/main/kubernetes/media.

Workload	Purpose
Emby	Primary media server
Flaresolverr	Indexer challenge helper
Immich	Photo and video library
Jellyfin	Secondary media server
Lidarr	Music library automation
Ombi	Media request management
Prowlarr	Indexer management
qBittorrent	Download client
Radarr	Movie library automation
Recyclarr	Servarr profile synchronization
Sonarr	TV library automation

Applications

General applications remain under clusters/main/kubernetes/apps.

Category	Workloads
Identity and access	Authentik, Vaultwarden
Development and AI	Code Server, Gitea, Ollama
Home and personal	Home Assistant, TeslaMate
Productivity	Nextcloud, Proton Mail Bridge
Dashboards and utilities	Homepage, IT-Tools, Kubernetes Dashboard, Static
External service portals	Proxmox GUI, TrueNAS GUI
Networking helper	Cloudflare DDNS

GitOps and Secrets

• Flux reconciles the root Kustomization at clusters/main/kubernetes.
• Workloads are grouped by operational domain, but retain their existing namespaces and Flux object names when moved.
• Helm and OCI sources are declared under repositories/ and clusters/main/kubernetes/flux-system.
• Renovate updates pinned chart versions, container tags, and digests.
• SOPS encryption rules cover clusterenv.yaml, *.secret.yaml, and secret-bearing values files.
• Plaintext credentials must never be committed.

Prerequisites

• ClusterTool CLI
• SOPS with the cluster Age key
• kubectl
• talosctl
• Flux CLI

Reconciliation Workflow

1. Clone the repository and configure the SOPS Age key.
2. Make changes in a focused branch.
3. Render the affected Kustomization and validate resources against the cluster API.
4. Open a pull request and wait for repository checks.
5. Merge the pull request; Flux applies the desired state and reports reconciliation status.

License

AGPL-3.0