README.md

Homelab

K8S cluster built with Ansible and managed using ArgoCD for GitOps

           

       

Welcome to my homelab! The repository is mostly focused on a modest kubernetes cluster with one control plane/node running all of my self hosted services and storage, but it also serves as the Infrastructure-as-Code (IaC) for my entire home network and devices, to include: an OpnSense gateway/firewall, a couple of workstations, wireless devices, and a Cisco switch. Ultimately, this will include all applications for managing home IT systems.

🤯 Features

• Kubernetes cluster deployment using kubeadm
• Infrastructure Automation with Ansible to provision hosts, clusters, devices, etc.
• Offline Root CA / Scripted PKI management using openssl(1)
• Manage cluster state and apps using GitOps and ArgoCD
• FreeIPA server
• RADIUS server
• Remote access via VPN

⌨️ Getting Started

python3 -m venv .venv
source .venv/bin/activate
pip install -U -r requirements.txt
ansible-galaxy collection install -U -r requirements.yaml
ansible-playbook homelab.yml

🍇 Cluster

Infrastructure Automation

Host buildout is handled by Ansible automation. The whole lab is built out from a top level playbook, with segment specific playbooks under the playbooks/ directory. (As a convention, all Ansible yaml files are suffixed .yml to allow VSCode to distinguish between those and all other yaml files.) The full task list can be found in the infrastructure folder, but as an overview, it will:

• Install system packages and any other necessary system related setup
• Pull down cluster images and binaries
• Install container runtime and start kubelet
• Run kubeadm to setup to create cluster
• Creates a separate user to continue setting up the cluster with to get away from using the admin credentials
• Applies CNI configuration
• Generates Application files for every cluster app and drops them into cluster/bootstrap and Kustomization files intocluster/apps for the respective apps
• Bootstraps the cluster by starting ArgoCD and then applying cluster/cluster.yaml

GitOps

ArgoCD watches all subfolders under the cluster folder (see Directories below) and makes the changes to my cluster based on the YAML manifests.

The way Argo works for me here is (almost) every file in the cluster/bootstrap directory will define an argoproj.io/v1alpha1/Application that points to a corresponding folder under cluster/apps. The Application will apply any manifest files it finds in that directory, in addition to any Helm Charts or Kustomizations that may also be defined within the Application's spec. One or more Helm values.yaml files are in each directory and each helm definition in the Application refers to the specific values file to apply to that chart.

Directories

This Git repository contains the following top level directories.

📁 cluster         # Kubernetes cluster defined in code
├─📁 apps          # Apps deployed into my cluster grouped by namespace
├─📁 argocd        # Main Argo configuration of repository
└─📁 bootstrap     # Cluster initialization flies (Argo Applications) also grouped by namespace
📁 infrastructure  # Ansible files
├─📁 inventory     # Defines Host configurations and widest scoped variables
├─📁 pki           # Self-signed CA and subordinate CA certs for whole house and cluster
├─📁 roles         # Ansible roles that define the actual steps to accomplish these tasks
└─📁 terraform     # Terraform config for building VM hosts
📁 playbooks       # Ansible playbooks

🖥️ Tech Stack

Infrastructure

Logo	Name	Description
	Ansible	Automate bare metal provisioning and configuration
	ArgoCD	GitOps tool built to deploy applications to Kubernetes
	cert-manager	Cloud native certificate management
	CRI-O	OCI - Container Runtime
	Debian	Base OS for Kubernetes nodes
	External DNS	Synchronize exposed services and ingresses with DNS providers
	Flannel	Kubernetes Network Plugin
	Helm	The package manager for Kubernetes
	Ingress-nginx	Ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer
	kubeadm	Official command-line cluster management tool
	KVM	Linux Kernel Virtual Machine Hypervisor
	Kubernetes	Container Orchestration
	Libvirt	Virtualization API
	MetalLB	Bare metal load-balancer for Kubernetes
	OAuth2 Proxy	Forward Auth for OpenID Connect
	Prometheus	Systems monitoring and alerting toolkit
	QEMU	Open source machine emulator and virtualizer
	Terraform	Infrastructure provisioning automation
	ZeroTier	Virtual Networking that just works

Applications (by namespace)

Homepage

Icon	Application	Category	Description	Status	Version
	Homepage	Home	Landing page for exploring the cluster, with live widgets!	Deployed

Database

Icon	Application	Category	Description	Status	Version
	MySQL	Relational DB	SQL Database	Deployed
	PostgreSQL	Relational DB	via Cloudnative-PG operator	Deployed
	Redis	Caching	In-memory Key-Value store	Deployed

Downloads

Icon	Application	Category	Description	Status	Version
	qBittorrent	Downloader	BitTorrent client	Deployed
	Radarr	Movies	Movie Collection manager	Deployed
	Sonarr	TV	TV Series Collection manager	Deployed
	Lidarr	Music	Music Collection manager	Deployed
	Readarr	Ebooks	Ebook and audiobook collection manager	Deployed
	Prowlarr	Tracker	Tracker manager	Deployed
	Bazarr	Subtitles	Subtitle download manager

Home

Icon	Application	Category	Description	Status	Version
	Grocy	Services	ERP Beyond your fridge	Deployed
	Mealie	Services	Recipe Manager	Deployed
	Paperless-ngx	File Sharing	Document Management System	Deployed
	Home Assistant	Home Automation	Open source home automation	Deployed
	Homebox	Home inventory	Inventory and organization for the Home User	Deployed
	Mosquitto	MQTT Broker	Eclipse-foundation MQTT broker implementation	Deployed
	Owntracks	Location Tracking	Keep track of your own location	Deployed
	Frigate NVR	NVR	Home video monitoring	In Progress
	Z-Wave JS	Z-Wave Controller	Z-Wave Controller written in javascript	Deployed

Infrastructure Services

Icon	Application	Category	Description	Status	Version
	NetBox	Inventory	Full-scale network inventory	Deployed
	Keycloak	SSO	Identity and Access Management solution	Deployed
	Kubeshark	Network traffic	API traffic analyzer for Kubernetes
	Reloader	Configuration Management	Controller for rolling upgrades when ConfigMaps or Secret s hange	Deployed
	Vault	Services	Secrets and encryption management

Media

Icon	Application	Category	Description	Status	Version
	Calibre	Books	E-book collection manager	Deployed
	Audiobookshelf	Audio Books	Self-hosted audiobook and podcast server	Deployed
	Jellyfin	Media Server	The open source media server	Deployed
	Immich	Photos	Photo Management	Deployed
	ListenBrainz	Scrobble	Open Source scrobbler	Planned
	Photoprism	Photos	Photo Management	Deployed
	Navidrome	Music Streaming	Your Personal Streaming Service	Deployed

Services

Icon	Application	Category	Description	Status	Version
	Change Detection	Website Monitoring	Website Change Detection ... For Clever People	Deployed
	Linkding	Bookmark Sharing	Minimal bookmark Manager	Deployed
	LinkAce	Bookmark Sharing	Your self-hosted bookmark archive	Deployed
	Linkwarden	Bookmark Sharing	Collaborative Bookmark Manager	Deployed
	Stirling PDF	Document Editing	Self-hosted PDF editor	Deployed
	Wallabag	Article Saver	Save and classify articles. Read them later. Freely.	Deployed
	Wger	Health tracking	Workout and food tracker	Broken

Monitoring

Icon	Application	Category	Description	Status	Version
	Grafana	Dashboard	Operational dashboards	Deployed

Virtualized (and other off cluster) Apps

Icon	Application	Category	Description	Status	Version
	FreeIPA	Infrastructure	Full IdAM solution + PKI	Deployed
	MythTV	Media	Digital Video Recorder	Running directly on node

🤝 Thank you

• bjw-s/home-ops
• onedr0p/home-ops
• khuedoan/homelab
• gruberdev/homelab
• RickCoxDev/home-cluster
• billimek/k8s-gitops
• blackjid/k8s-gitops
• carpenike/k8s-gitops
• K8s-At-Home Project

 📈 Repository Stats

⭐ Stargazers

🎶 Repobeats