pando85/homelab

Small and energy-efficient self-hosting infrastructure.

Pando85's Homelab

This project utilizes Infrastructure as Code and GitOps to automate provisioning, operating, and updating self-hosted services in my homelab. Based in K3s, ArgoCD, Renovate and ZFS. It can be used as a highly customizable framework to build your own homelab.

What is a homelab?

Homelab is a laboratory at home where you can self-host, experiment with new technologies, practice for certifications, and so on. For more information about homelab in general, see the r/homelab introduction.

📖 Overview

This section provides a high level overview of the project. For further information, please see the documentation.

⛵ Kubernetes

This repo is focused in maintain in a GitOps practical way my home infrastructure. Ansible is used to deploy a simple K3s cluster. Managed by ArgoCD.

Installation

The cluster is running on Debian based distributions, deployed on bare-metal. We use custom Ansible playbooks and roles to setup the Kubernetes cluster.

Core components

• external-secrets: External Secrets Operator reads information from a Vault and automatically injects the values as Kubernetes Secrets.
• hashicorp/vault: A tool for secrets management, encryption as a service, and privileged access management.
• kubernetes-sigs/external-dns: Automatically manages DNS records from my cluster in a cloud DNS provider.
• jetstack/cert-manager: Creates SSL certificates for services in my Kubernetes cluster.
• kubernetes/ingress-nginx: Ingress controller to expose HTTP traffic to pods over DNS.
• openebs/zfs-localpv: CSI Driver for dynamic provisioning of Persistent Local Volumes for Kubernetes using ZFS.
• kanidm: A simple, secure and fast identity management platform.
• velero: Tool to safely backup and restore, perform disaster recovery, and migrate Kubernetes cluster resources and persistent volumes.

🔧 Hardware

Hostname	Device	Count	OS Disk Size	Data Disk Size	Ram	Operating System	Purpose
grigri	Supermicro Atom C2758 (A1SRi-2758F)	1	250GB SSD	3*4TB + 500GB (NVMe) RAIDZ + cache	32GB	Ubuntu 22.04	K3s server
prusik*	Ryzen 9 7950X (ASUS PRIME X670-P)	1	512GB	4*12TB + 2TB (NVMe) RAIDZ + cache	64GB	Ubuntu 24.04	k3s agent
k8s-odroid-hc4-i	Odroid-hc4	1	N/A	N/A	4GB	Armbian	K3s agent
prusik-ipmi	Raspberry Pi 4 Model B Rev 1.5	1	16GB	N/A	4GB	PiKVM	ipmi
pfsense	PC Engines APU2e4	1	60GB	N/A	4GB	pfSense/FreeBSD	Router
gs724t	Netgear gs724t	1	N/A	N/A	N/A	N/A	Switch
cerezo	Unifi UAP	1	N/A	N/A	N/A	N/A	AP
manzano	Unifi UAP	1	N/A	N/A	N/A	N/A	AP

* with Nvidia GeForce GTX 1060 3GB

Images

⭐ Features

• Common applications: Jellyfin, Gitea, arr, Nextcloud...
• Automated Kubernetes installation and management
• Installing and managing applications using GitOps
• Automatic rolling upgrade for OS and Kubernetes
• Automatically update apps (with approval if needed)
• Modular architecture, easy to add or remove features/components
• Automated certificate management
• Automatically update DNS records for exposed services
• Monitoring and alerting
• Single sign-on
• Automated backups

🌐 DNS

ExternalDNS is deployed in the cluster and configured to sync DNS records to Cloudflare.

All connections outside the cluster are handled with TLS using cert-manager with Let's Encrypt.

Load Balancer

Cilium is configured with BGP control plane, both on my router and within the Kubernetes cluster.

Ingress Controllers

For external access, port forwarding is configured for ports 80 and 443, directing traffic to the load balancer IP of the Kubernetes ingress controller.

There are also another ingress controller for internal use.

Internal DNS

internal.grigri.cloud domain is used. Configured as:

annotations:
  cert-manager.io/cluster-issuer: letsencrypt-prod-dns
  external-dns.alpha.kubernetes.io/enabled: "true"

External DNS

grigri.cloud domain is used. Configured as:

annotations:
  cert-manager.io/cluster-issuer: letsencrypt-prod-dns
  external-dns.alpha.kubernetes.io/enabled: "true"
  external-dns.alpha.kubernetes.io/target: grigri.cloud

🤝 Thanks

Thanks to all folks who donate their time to the Kubernetes @Home community. A lot of inspiration for my cluster came from those that have shared their clusters over at awesome-home-kubernetes.

homelab's Issues

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Location: .github/renovate.json5
Error type: The renovate configuration file contains some invalid settings
Message: Invalid configuration option: forkInclusion

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Repository problems

Renovate tried to run on this repository, but found these problems.

• WARN: Found renovate config warnings

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• qbittorrent: Update ghcr.io/onedr0p/qbittorrent:4.6.5 Docker digest to 60bbc09
• argocd: Update Helm release argo-cd to v7.4.3
• kube-system: Update Helm release cilium to v1.16.1
• sonarr: Update ghcr.io/onedr0p/sonarr-develop Docker tag to v4.0.8.2158
• velero: Update Helm release velero to v7.1.5
• workflows: Update renovatebot/github-action action to v40.2.6
• immich: Update ghcr.io/immich-app/immich-machine-learning Docker tag to v1.112.1
• immich: Update ghcr.io/immich-app/immich-server Docker tag to v1.112.1
• monitoring: Update Helm release kube-prometheus-stack to v61.9.0

Edited/Blocked

These updates have been manually edited so Renovate will no longer make changes. To discard all commits and start over, click on a checkbox.

• k3s: Update dependency k3s-io/k3s to v1.29.7+k3s1
• kube-system: Update Helm release nvidia-device-plugin to v0.16.2
• mintpsicologia: Update Helm release wordpress to v23.1.3

Detected dependencies

github-actions

.github/workflows/docs.yaml

• actions/checkout v4

.github/workflows/schedule-renovate.yaml

• actions/checkout v4
• tibdex/github-app-token v2
• renovatebot/github-action v40.2.5@0c94129d48b4e92addf23686b8a735b3057a0448

helm-values

apps/antdroid/values.yaml

• nginx 1.27.0-alpine

apps/bazarr/values.yaml

• ghcr.io/onedr0p/bazarr 1.4.3@sha256:d2b70813f7d636fb1ab3448e13ca4074630b63216c6c6d02d034cd5d9e938ea3
• registry.k8s.io/git-sync/git-sync v4.2.4

apps/cross-backups/values.yaml

apps/esphome/values.yaml

• debian 12.6-slim
• ghcr.io/esphome/esphome 2024.7.3@sha256:cb75d2af6df19c2415428cdfe604c82202914c7f54aaed7084a2f51fb3d20f7f

apps/flaresolverr/values.yaml

• ghcr.io/flaresolverr/flaresolverr v3.3.21

apps/freshrss/values.yaml

• freshrss/freshrss 1.24.1
• freshrss/freshrss 1.24.1

apps/github-exporter/values.yaml

• githubexporter/github-exporter 1.2.0

apps/gow/values.yaml

• ghcr.io/games-on-whales/sunshine edge@sha256:5c7e9e9ba4a700e9441abfd0a2aaf963b0b135173919f9948d2958f8f92247e6
• ghcr.io/games-on-whales/xorg edge@sha256:e32455a355367c700e692afa93ba5a481fa29afa9c9b0195fa171c0da21413ca
• ghcr.io/games-on-whales/pulseaudio edge@sha256:94e68db623d134b28f8f96ccd3f9c88945c590311c5d121949e992ce0cd45fbc
• ghcr.io/games-on-whales/steam edge@sha256:7113cf23e835a71b7d4bdb1eec1868aa6d640cb7eadc8e23d217ac335d83bf04

apps/home-assistant/values.yaml

• ghcr.io/onedr0p/home-assistant 2024.8.1@sha256:d315bfaf6e9d5f612f4d773217c80cfb4b87f582b4278257739f792651221cdc
• debian 12.6-slim
• acockburn/appdaemon 4.4.2
• pando85/wyoming-whisper 2.0.0
• rhasspy/wyoming-piper 1.5.0
• rhasspy/wyoming-openwakeword 1.10.0
• ghcr.io/erkexzcx/valetudopng v1.0.17

apps/http-echo/values.yaml

• mendhak/http-https-echo 33

apps/immich/values.yaml

• ghcr.io/immich-app/immich-server v1.111.0
• ghcr.io/immich-app/immich-server v1.111.0
• ghcr.io/immich-app/immich-machine-learning v1.111.0
• public.ecr.aws/docker/library/redis 7.4.0

apps/jellyfin/values.yaml

• jellyfin/jellyfin 10.9.9

apps/jellyseerr/values.yaml

apps/m-rajoy-api/values.yaml

• pando85/quotes-simple-web-api 1.0.0

apps/m-rajoy-front/values.yaml

• pando85/quotes-simple-web-front 1.0.0

apps/mosquitto-tls/values.yaml

• public.ecr.aws/docker/library/eclipse-mosquitto 2.0.18
• public.ecr.aws/docker/library/eclipse-mosquitto 2.0.18

apps/mosquitto/values.yaml

• public.ecr.aws/docker/library/eclipse-mosquitto 2.0.18
• public.ecr.aws/docker/library/eclipse-mosquitto 2.0.18
• sapcc/mosquitto-exporter 0.8.0

apps/navidrome/values.yaml

• deluan/navidrome 0.52.5

apps/nextcloud/values.yaml

• nextcloud 29.0.4
• redis 7.4.0

apps/prowlarr/values.yaml

• ghcr.io/onedr0p/prowlarr-nightly 1.21.2.4648@sha256:1cb047a17519c87e015b2585d1bdf0234ef35f1eb0addf13d4ad92d4db858700

apps/qbittorrent/values.yaml

• ghcr.io/onedr0p/qbittorrent 4.6.5@sha256:c019af23966ebafcaf1713d4553bc043246858b711a7d57d8bee358a89990a3e
• ghcr.io/esanchezm/prometheus-qbittorrent-exporter latest@sha256:340a6d43797e2944a6babd6cadc7160e87d30b57bdf401aef57eccbd600d98ce

apps/radarr/values.yaml

• ghcr.io/onedr0p/radarr-develop 5.8.3.8933@sha256:da6094f6cc4dc95af194612a8a4d7db4fc27ff4a6e5748c2e6d5dd7be9ed69a7

apps/sonarr/values.yaml

• ghcr.io/onedr0p/sonarr-develop 4.0.8.2093@sha256:83bbdf166ba7430a82eed0e8e35e0fa1b071b0ea618e2c80386756bbb71eb818

apps/special-web/values.yaml

• nginx 1.27.0-alpine

apps/stump/values.yaml

• aaronleopold/stump nightly@sha256:4b9a6f2aa90ace908c480f4b31adefd23d48ab38e97fefbe6c5ae1ac50192637

apps/telegram-bot/values.yaml

• pando85/troll-bot 1.0.1

apps/transcoder/values.yaml

• ghcr.io/pando85/gearr 0.1.11-server
• rabbitmq 3.13.6

apps/unifi/values.yaml

• jacobalberty/unifi v8.3.32

apps/unpackerr/values.yaml

• golift/unpackerr 0.14.5

apps/wallabag/values.yaml

• wallabag/wallabag 2.6.9

platform/minio/values.yaml

platform/velero/values.yaml

• velero/velero-plugin-for-aws v1.10.0
• openebs/velero-plugin 3.6.0

system/kanidm/values.yaml

• kanidm/server 1.3.2

system/oauth2-proxy/values.yaml

• redis 7.4.0

helmv3

apps/antdroid/Chart.yaml

• app-template 3.3.2

apps/bazarr/Chart.yaml

• app-template 3.3.2

apps/cross-backups/Chart.yaml

• minio 5.2.0

apps/esphome/Chart.yaml

• app-template 3.3.2

apps/freshrss/Chart.yaml

• app-template 3.3.2

apps/github-exporter/Chart.yaml

• app-template 3.3.2

apps/gow/Chart.yaml

• app-template 3.3.2

apps/home-assistant/Chart.yaml

• app-template 3.3.2

apps/http-echo/Chart.yaml

• app-template 3.3.2

apps/immich/Chart.yaml

• app-template 3.3.2

apps/jellyfin/Chart.yaml

• app-template 3.3.2

apps/jellyseerr/Chart.yaml

• app-template 3.3.2

apps/m-rajoy-api/Chart.yaml

• app-template 3.3.2

apps/m-rajoy-front/Chart.yaml

• app-template 3.3.2

apps/mintpsicologia/Chart.yaml

• wordpress 23.0.11

apps/mosquitto-tls/Chart.yaml

• app-template 3.3.2

apps/mosquitto/Chart.yaml

• app-template 3.3.2

apps/navidrome/Chart.yaml

• app-template 3.3.2

apps/nextcloud/Chart.yaml

• nextcloud 5.5.2
• app-template 3.3.2

apps/prowlarr/Chart.yaml

• app-template 3.3.2

apps/qbittorrent/Chart.yaml

• app-template 3.3.2

apps/radarr/Chart.yaml

• app-template 3.3.2

apps/sonarr/Chart.yaml

• app-template 3.3.2

apps/special-web/Chart.yaml

• app-template 3.3.2

apps/stump/Chart.yaml

• app-template 3.3.2

apps/telegram-bot/Chart.yaml

• app-template 3.3.2

apps/transcoder/Chart.yaml

• app-template 3.3.2

apps/unifi/Chart.yaml

• app-template 3.3.2

apps/unpackerr/Chart.yaml

• app-template 3.3.2

apps/wallabag/Chart.yaml

• app-template 3.3.2

bootstrap/argocd/Chart.yaml

• argo-cd 7.4.2

platform/external-secrets/Chart.yaml

• external-secrets 0.10.0

platform/git/Chart.yaml

• gitea 10.4.0

platform/minio/Chart.yaml

• minio 5.2.0

platform/postgres-operator/Chart.yaml

• postgres-operator 1.12.2

platform/reloader/Chart.yaml

• reloader 1.0.121

platform/vault/Chart.yaml

• vault-operator 1.19.0

platform/velero/Chart.yaml

• velero 7.1.4

system/cert-manager/Chart.yaml

• cert-manager v1.15.2

system/external-dns/Chart.yaml

• external-dns 1.14.5

system/ingress-nginx-external/Chart.yaml

• ingress-nginx 4.11.1

system/ingress-nginx/Chart.yaml

• ingress-nginx 4.11.1

system/kanidm/Chart.yaml

• app-template 3.3.2

system/kured/Chart.yaml

• kured 5.5.0

system/oauth2-proxy/Chart.yaml

• oauth2-proxy 7.7.9
• app-template 3.3.2

system/snapscheduler/Chart.yaml

• snapscheduler 3.4.0

system/zfs-localpv/Chart.yaml

• zfs-localpv 2.6.0

kustomize

apps/flaresolverr/kustomization.yaml

• app-template 3.3.2

system/kube-system/kustomization.yaml

• cilium 1.16.0
• nvidia-device-plugin 0.16.1
• gpu-feature-discovery 0.15.0

system/kyverno/kustomization.yaml

• kyverno 3.2.6

system/loki/kustomization.yaml

• loki 6.10.0
• promtail 6.16.4

system/monitoring/kustomization.yaml

• kube-prometheus-stack 61.8.0
• prometheus-blackbox-exporter 9.0.0
• prometheus-smartctl-exporter 0.10.0

regex

metal/roles/k3s/defaults/main.yml

• k3s-io/k3s v1.29.6+k3s1

metal/roles/zfs_exporter/defaults/main.yml

• pdf/zfs_exporter 2.3.2

platform/vault/templates/vault.yaml

• vault 1.13.3

system/monitoring/resources/long-term-metrics/prometheus.yaml

• quay.io/prometheus/prometheus v2.54.0
• quay.io/prometheus/prometheus v2.54.0

system/system-upgrade/k3s/kustomization.yaml

• k3s-io/k3s v1.29.6+k3s1

system/system-upgrade/kustomization.yaml

• rancher/system-upgrade-controller v0.13.4

metal/roles/k3s/defaults/main.yml

• k3s-io/k3s v1.29.6+k3s1

metal/roles/zfs_exporter/defaults/main.yml

• pdf/zfs_exporter 2.3.2

platform/vault/templates/vault.yaml

• vault 1.13.3

system/monitoring/resources/long-term-metrics/prometheus.yaml

• quay.io/prometheus/prometheus v2.54.0
• quay.io/prometheus/prometheus v2.54.0

system/system-upgrade/k3s/kustomization.yaml

• k3s-io/k3s v1.29.6+k3s1

system/system-upgrade/kustomization.yaml

• rancher/system-upgrade-controller v0.13.4

Add Infro PR Checks?

I noticed that this repo uses Argo CD, and I thought I’d let you know that I recently released a Github app called Infro that several companies use internally that allows Argo CD users to preview Kubernetes changes in Github pull requests before they merge. I’m providing it for free to open source projects (here’s an example in the wild). Here’s a setup guide with links to documentation. It’s in early stages, so I’m sure there will be warts. All feedback is welcome!