A GitOps-managed Kubernetes homelab built with K3S, Flux CD, and a variety of self-hosted applications.

This repository contains the configuration for a complete homelab infrastructure based on Kubernetes. It uses a GitOps approach with Flux CD to manage deployments, ensuring that the cluster state always matches what's defined in this repository.

The homelab includes:

• Media management (Sonarr, Radarr, Jellyfin, etc.)
• Home automation (Home Assistant, MQTT, Zigbee2MQTT, Z-Wave JS UI)
• Photo management (Immich)
• Documentation (Outline)
• Authentication (Authentik)
• Monitoring (Prometheus, Grafana, Gatus)

The homelab runs on a K3S Kubernetes cluster with the following nodes:

• 3 server nodes (node1, node2, node3)

node1.layertwo.dev (172.31.0.10)
node2.layertwo.dev (172.31.0.11)
node3.layertwo.dev (172.31.0.12)

The network is managed by:

• MetalLB: Provides load balancing with two IP pools:

  • Internal pool: 172.31.0.20-172.31.0.29
  • External pool: 172.31.0.30-172.31.0.39

• Traefik: Serves as the ingress controller with two instances:

  • Internal Traefik (172.31.0.20): For internal services
  • External Traefik (172.31.0.30): For external access with TLS configuration

• External DNS: Automatically manages DNS records in Cloudflare

• Cloudflare DDNS: Custom container that updates Cloudflare DNS records with the current external IP

Storage is provided by:

• Democratic CSI: Connects to a TrueNAS server (sunbeam.layertwo.lan) for NFS storage
• Longhorn: Distributed block storage for Kubernetes

Backups are stored in Cloudflare R2 (S3-compatible storage) with dedicated buckets:

• layertwo-dev-volsync: For VolSync backups (persistent volume backups)
• layertwo-dev-cloudnativepg: For CloudNative PostgreSQL backups
• layertwo-dev-tofu: For Terraform state files

• K3S: Lightweight Kubernetes distribution
• Flux CD: GitOps controller that ensures the cluster state matches the repository
• SOPS: Secrets management with encryption
• VolSync: Persistent volume backup and restore
• Democratic CSI: CSI driver for TrueNAS NFS storage
• Longhorn: Distributed block storage
• System Upgrade Controller: Manages K3S upgrades

• Traefik: Ingress controller with internal and external instances
• MetalLB: Load balancer for Kubernetes services
• External DNS: Automatic DNS management
• Cloudflare DDNS: Dynamic DNS updater

• Democratic CSI: CSI driver for TrueNAS NFS storage
• Longhorn: Distributed block storage
• CloudNative PG: PostgreSQL operator

• Cert Manager: Automatic TLS certificate management
• Authentik: Identity provider and SSO solution

• Prometheus & Grafana: Metrics collection and visualization
• Gatus: Service health checking

• Sonarr: TV show management
• Radarr: Movie management
• Bazarr: Subtitle management
• Prowlarr: Indexer management
• qBittorrent: Download client
• Jellyfin: Media server
• Recyclarr: Configuration management for *arr apps

• Home Assistant: Home automation platform
• MQTT: Message broker for IoT devices
• Zigbee2MQTT: Bridge for Zigbee devices
• Z-Wave JS UI: Management for Z-Wave devices

• Immich: Self-hosted photo and video backup solution

• Outline: Wiki and knowledge base

• Authentik: Identity provider and SSO solution

A Python script that updates DNS records on Cloudflare dynamically. It retrieves the external IP address of the machine it's running on and updates the specified DNS record accordingly.

Container images for CloudNative PostgreSQL with the pgvecto.rs extension installed, adding vector search capabilities to PostgreSQL for AI applications.

A packaging of the BIRD routing software for use with PureLB, a load-balancer orchestrator for Kubernetes clusters.

The bootstrap directory contains utilities for setting up the K3S cluster:

1. Install k3sup:

curl -sLS https://get.k3sup.dev | sh
sudo cp k3sup /usr/local/bin/k3sup

2. Create a k3sup plan using the devices.json file:

k3sup plan \
  devices.json \
  --user $USER \
  --servers 3 \
  --server-k3s-extra-args "--disable traefik" \
  --background > bootstrap.sh

3. Execute the bootstrap script to set up the K3S cluster.

After the K3S cluster is running, Flux CD is installed to manage the GitOps workflow. Flux CD synchronizes the cluster state with this repository, ensuring that all applications and configurations are deployed as defined.

The cloud infrastructure is managed using Terraform CDK (cdktf) with the following components:

• Cloudflare R2: S3-compatible storage for backups
  • VolSync backups
  • CloudNative PostgreSQL backups
  • Terraform state files

• Cloudflare: DNS management with automatic updates via External DNS and Cloudflare DDNS

Detailed documentation for the various components of the homelab can be found in the docs directory:

• Networking: Details about the networking setup
• Storage: Information about the storage setup
• Media Stack: Documentation for the media management applications
• Home Automation: Details about the home automation setup
• Monitoring: Information about the monitoring stack
• Authentication: Documentation for the authentication setup
• Backup Strategy: Details about the backup strategy

This project is licensed under the terms of the LICENSE file included in the repository.