Skip to content
ronaldlokersPublic

About

This repository contains the complete infrastructure and application configuration for a Kubernetes homelab environment. Everything is managed declaratively through Git, with Flux CD automatically reconciling the cluster state.

Topics

Resources

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

Homelab

GitOps-managed Kubernetes homelab using Flux CD.

Flux k3s Kubernetes Longhorn Renovate Grafana Raspberry Pi

Overview

This repository contains the complete infrastructure and application configuration for a Kubernetes homelab environment. Everything is managed declaratively through Git, with Flux CD automatically reconciling the cluster state.

Quick Start

Environment Nodes Storage Load Balancing Version
Staging 1 server + 1 agent (k3d) local-path k3d built-in K3s v1.31.5
Production 3 control planes (HA) Longhorn (3-replica) MetalLB K3s v1.33.6

Services

Service Staging Production
Commafeed commafeed.staging.ronaldlokers.nl commafeed.ronaldlokers.nl
Homepage homepage.staging.ronaldlokers.nl homepage.ronaldlokers.nl
Immich immich.staging.ronaldlokers.nl immich.ronaldlokers.nl
Linkding linkding.staging.ronaldlokers.nl linkding.ronaldlokers.nl
Nightscout nightscout.staging.ronaldlokers.nl nightscout.ronaldlokers.nl
Speedtest Tracker N/A speedtest.ronaldlokers.nl
Grafana grafana.staging.ronaldlokers.nl grafana.ronaldlokers.nl
Longhorn N/A longhorn.ronaldlokers.nl

Hardware

Staging

Runs in a Proxmox VM on hightower (Intel NUC7i3DNHE):

  • Platform: k3d (K3s in Docker)
  • Host: Ubuntu Server VM with Docker
  • IP: 10.0.40.52

Production

Runs in a Sipeed NanoCluster with Raspberry Pi CM5 modules:

  • 3 nodes: kube-srv-1, kube-srv-2, kube-srv-3
  • Compute Module: Raspberry Pi CM5
  • RAM: 16GB per node
  • Storage: 64GB eMMC per node
  • IPs: 10.0.40.101, 10.0.40.102, 10.0.40.103
Sipeed NanoCluster

Sipeed NanoCluster

Raspberry Pi CM5

Raspberry Pi Compute Module 5

Stack

  • GitOps: Flux CD - Continuous delivery from Git
  • Automation: Renovate - Automated dependency updates
  • Certificates: cert-manager - Automatic TLS with Let's Encrypt
  • Ingress: Traefik - Ingress controller
  • Load Balancer: MetalLB - Bare-metal load balancer (production only)
  • Storage: Longhorn - Distributed block storage (production only)
  • Database: CloudNative-PG - PostgreSQL operator with DocumentDB extension for MongoDB compatibility
  • Monitoring: kube-prometheus-stack - Prometheus & Grafana
  • Logging: Loki + Grafana Alloy - Log aggregation and querying (staging)
  • Applications:

Documentation

  • Setup Guide - How to set up staging and production clusters
  • Architecture - Repository structure, deployment flow, and networking
  • Security - SOPS encryption and secrets management
  • Network Security - NetworkPolicy implementation and zero-trust architecture
  • Stack Details - Detailed component information
  • War Stories - Real-world challenges and solutions from building this cluster

Key Features

High Availability (Production)

  • Control Plane: 3-node HA with embedded etcd (survives 1-node failure)
  • Storage: Longhorn with 3-replica redundancy (survives 2-node failure)
  • Load Balancing: MetalLB provides single VIP (10.0.40.100) for ingress
  • Database: PostgreSQL cluster with 3 instances and DocumentDB extension for redundancy
  • Certificates: Automatic TLS with Let's Encrypt DNS-01 challenges

GitOps Workflow

  1. Push changes to Git repository
  2. Flux detects changes within about a minute (or instantly with manual reconciliation)
  3. Flux applies changes to the cluster
  4. Health checks ensure successful deployment

Automated Updates

  • Renovate scans for dependency updates hourly
  • Creates pull requests with changelogs
  • Review and merge to automatically deploy updates

Security & Compliance

  • Zero-Trust Networking: NetworkPolicies enforce default-deny with explicit allow rules
  • Namespace Isolation: Prevents lateral movement between services
  • Egress Control: Limits external communication to approved endpoints
  • TLS Everywhere: Automatic certificates with Let's Encrypt DNS-01 challenges
  • Secrets Management: SOPS encryption with age keys (separate per environment)
  • Private keys stored in Proton Pass (not in Git)

Automated Backups

  • PostgreSQL backups to Backblaze B2 object storage
  • Daily automated backups with 14-30 day retention
  • Point-in-time recovery (PITR) capability
  • Continuous WAL archiving for near-zero data loss
  • Off-cluster storage survives complete cluster failure

Repository Structure

.
├── clusters/              # Flux entry points for each environment
├── infrastructure/
│   ├── controllers/       # Core services (cert-manager, cloudnative-pg, longhorn, metallb, renovate)
│   └── configs/          # Infrastructure configuration (issuers, database clusters, middlewares)
├── apps/                 # Applications (linkding, homepage)
├── monitoring/           # Observability (kube-prometheus-stack, dashboards)
└── docs/                 # Documentation

See Architecture for detailed structure information.

Contributing

This is a personal homelab repository, but feel free to use it as inspiration for your own setup!

License

This repository is provided as-is for educational purposes.

About

This repository contains the complete infrastructure and application configuration for a Kubernetes homelab environment. Everything is managed declaratively through Git, with Flux CD automatically reconciling the cluster state.

Topics

Resources

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Used by

Contributors

Languages