homelab

Middle-Earth Cluster homelab repository

A place for experimentation, fun and never-ending YAML files.

_{“Even the smallest server can run the mightiest workloads.” — 🧙‍♂️ Gandalf, the homelabber wizard}

_{Built with viele ☕️ by Josimar Silva. | Delivering greatness from the trenches of Gondor.}

Table of Contents

• Introduction
• Middle Earth Cluster
• Software
• Network
• Storage
• Secret Management
• Development
• Acknowledgments
• References

Introduction

This repository contains the entire configuration of my Kubernetes-based homelab. It is managed using GitOps principles with FluxCD, Renovate and GitHub Actions. The goal of this project is to create a stable, reproducible and automated homelab environment for learning and experimentation.

Middle Earth Cluster

The heart of the homelab is a Kubernetes cluster named "Middle-Earth". This cluster is built on top of Talos OS and its Talos configuration is provisioned from a private repository.

Server Rack

The server rack is a custom-built 19" rack that houses all the hardware for the homelab.

It includes the mini-PCs, switch, firewall, patch panel, NAS and UPS (and a companion NUT server built with Raspberry Pi 4).

Nodes

The k8s cluster consists of the following nodes:

Name	Role	Model	Category	CPU	RAM	GPU	Storage
gandalf	Control Plane	EliteDesk 800 G3 Mini	hobbit-md-i5	Intel i5-7500t	16GB	N/A	256GB NVMe
sam	Worker	EliteDesk 800 G3 Mini	hobbit-md-i5	Intel i5-7500t	16GB	N/A	500GB NVMe
pipin	Worker	EliteDesk 800 G3 Mini	hobbit-sm-i3	Intel i3-6100T	16GB	N/A	500GB NVMe
merry	Worker	EliteDesk 800 G3 Mini	hobbit-sm-i3	Intel i3-6100T	16GB	N/A	500GB NVMe
gollum	Worker	Lenovo G400s Laptop	hobbit-bg-i7	Intel i7-3612QM	16GB	N/A	1TB Sata SSD
frodo	Worker	Custom Build	hobbit-bg-r7	AMD Ryzen 7 5700	32GB	N/A	500GB NVMe
saruman	LLM Server	Custom Build	N/A	AMD Ryzen 8600G	128GB	NVIDIA 3090	1TB NVMe

Software

The cluster runs a variety of software, from infrastructure components to user-facing applications.

Apps

Application	Description
calibre-web-automated	A self-hosted web application for browsing, reading, and downloading ebooks from Calibre library.
flash-slothmore	A bot that crawls the Berlin Service Portal to find available appointments.
foldingathome	Distributed computing for protein folding research, contributing to disease studies.
hello-from-gondor	Simple dashboard with basic cluster metrics.
homepage	A modern, customizable application dashboard with service monitoring and Kubernetes integration.
linkwarden	A self-hosted bookmark and link management system.
ollama	A self-hosted LLM platform with Open WebUI for running and managing AI models locally.
pi-hole	A network-wide ad blocker doubling as the LAN DNS server.
speedtest-tracker	A tool to track internet speed over time.

Infrastructure

Component	Description
cert-manager	Manages TLS certificates for the cluster.
cloudnative-pg	Manages PostgreSQL clusters in Kubernetes.
core-dns	Customized CoreDNS configuration with TCP forwarding and enhanced caching for cluster DNS.
flux-system	The GitOps operator that powers the cluster.
gatus	Monitoring dashboard with the status of apps.
gateway-api	Kubernetes Gateway API CRDs for advanced traffic routing.
headlamp	Kubernetes web UI with plugins for Flux, Cert-Manager, and Trivy integration.
internal-dns	An instance of external-DNS acting as a local DNS using Pi-hole as the DNS server.
longhorn	Distributed block storage for persistent volumes.
metallb	Bare-metal load balancer for Kubernetes.
nginx-gateway-fabric	NGINX implementation of Gateway API for external access with improved separation of infrastructure and application routing.
nodelocaldns	Local DNS cache running on each node to reduce DNS query latency and improve reliability.
onepassword	1Password integration for managing secrets.
prometheus	Monitoring stack with Prometheus, Grafana, and Alertmanager for metrics collection and visualization.
renovate	Automated dependency updates.
trivy-operator	Kubernetes security operator for vulnerability scanning, compliance checks, and configuration auditing.

One Chart to rule them all

This project uses a custom-made Helm chart called one-chart. This chart is designed to be flexible and reusable, and it is used to deploy all the applications that do not have a dedicated Helm chart available.

PostgreSQL Cluster Chart

This project includes a custom Helm chart for deploying PostgreSQL clusters using CloudNativePG, located at charts/postgresql-cluster.

Network

The network is segmented into multiple VLANs to provide security and isolation between different types of traffic. The firewall is managed by OPNsense, which is running on a dedicated appliance.

All the nodes in the Kubernetes cluster are connected to an isolated VLAN.

metallb is used to provide LoadBalancer services for the applications.

internal-dns provides name resolution for the services in the LAN by propagating the name records to Pi-hole.

Storage

Persistent storage is provided by longhorn. longhorn is a distributed block storage system that provides persistent volumes for stateful applications.

For backups, a QNAP TS-453E NAS is used as an NFS share. Longhorn is configured to use this NFS share to back up all the persistent volumes of the cluster.

Secret Management

Secrets are managed using onepassword and the 1Password Connect Operator. The operator syncs secrets from a 1Password vault to Kubernetes secrets. This allows for a secure and centralized way to manage secrets.

Development

Validation and Testing

The repository includes automated validation for configuration files:

Renovate Configuration Validation

Validate the Renovate configuration locally before committing:

just validate-renovate

This validates renovate.json using the official Renovate config validator, checking for:

• JSON syntax errors
• Schema compliance
• Configuration migration requirements
• Custom manager regex patterns

The validation also runs automatically in CI when changes are made to renovate.json.

Other Validations

# Run YAML linting, shellcheck, helm lint, and kubeconform
just lint

# Format shell scripts and YAML files
just format

Acknowledgments

This project would not have been possible without the amazing content produced by the homelab community. I would like to express my gratitude to the following individuals for been a great source of information and inspiration:

• Mischa Van den Burg - GitHub
• Techno Tim
• Christian Lempa
• Dave's Garage
• Jeff Geerling
• Raid Owl
• Home Network Guy
• Hardware Haven

The ease with which I was able to set up this Kubernetes cluster, compared to my first NAS build over a decade ago, is a testament to the quality of the content and the collaborative spirit of the homelab community.

---

References

• Kubernetes
• Talos OS
• FluxCD
• Renovate
• one-chart