🏠 homelab-gitops

My Kubernetes cluster managed with ArgoCD.

⚙️ Hardware (2 nodes)

Device	Name	Specs	OS	Role
Lenovo ThinkCentre M75q-2	homelab2	Ryzen 5 Pro 5650GE (6 core / 12 threads) / 24GB RAM / 256GB + 1TB SSD	NixOS	k8s controller+worker node
Lenovo ThinkCentre M75q-2	homelab3	Ryzen 5 Pro 5650GE (6 core / 12 threads) / 24GB RAM / 256GB + 1TB SSD	NixOS	k8s worker node

To access my apps, I expose them directly on the internet with port-forwarding on my router.

✨ Features

• Kubernetes cluster deployed with k0s
• GitOps deployment with ArgoCD and Helm
• Simple flat directory structure: argocd-apps contains ArgoCD applications deploying umbrella Helm charts in k8s-apps
• Fully automated HTTPS exposition using cert-manager, external-dns and ingress-nginx
• Authentication of sensitive apps with oauth2-proxy with GitLab as an OAuth2 provider
• Free endpoint security using Crowdsec
• Secrets management with external-secrets and GitLab CI/CD variables
• Dynamic volume provisioning and synchronous replication across nodes with Longhorn
• Offsite data backup using Velero and Backblaze B2
• Easy Backblaze-to-disk backup synchronization with Kopia and a custom script
• PostgreSQL database management with CloudNativePG
• Observability with Prometheus, Grafana, Loki and Opentelemetry Collector
• Alerting with Alertmanager and a Telegram Bot
• Thorough HTTP / PostgreSQL status checks with go-healthcheck and Gatus
• Automated updates with Renovate (even linuxserver images!)
• Any app you'd want to host! Currently, Nextcloud, Immich, Paperless-ngx and more (see below)

💻 What's currently deployed in my cluster ?

This is an automatically updated list of the apps I have configured and/or deployed. Click on an app to check its Helm configuration.

App	Description	Is deployed
argocd	Declarative, GitOps continuous delivery tool for Kubernetes	✅
arr-stack	Arr Stack	✅
blackbox-exporter	Allows blackbox probing of endpoints over HTTP, HTTPS, DNS, TCP, ICMP and gRPC	✅
calibre-web	Web app for browsing, reading and downloading eBooks stored in a Calibre database	✅
cert-manager	Automatically provision and manage TLS certificates in Kubernetes	✅
cloudnative-pg	CloudNativePG is a comprehensive platform designed to seamlessly manage PostgreSQL databases within Kubernetes environments, covering the entire operational lifecycle from initial deployment to ongoing maintenance	✅
convertx	Self-hosted online file converter	✅
crowdsec	Open-source and participative security solution offering crowdsourced protection against malicious IPs and access to the most advanced real-world CTI	✅
dead-drop	My recreation of a dead drop application to securely share information	❌
external-dns	Configure external DNS servers (AWS Route53, Google CloudDNS and others) for Kubernetes Ingresses and Services	✅
external-secrets	External Secrets Operator reads information from a third-party service like AWS Secrets Manager and automatically injects the values as Kubernetes Secrets	✅
go-healthcheck	Simple HTTP healthchecks	✅
headscale	An open source, self-hosted implementation of the Tailscale control server	❌
home-assistant	Open source home automation that puts local control and privacy first	✅
homepage	A highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations	✅
httpbin	Echoes request data as JSON	✅
immich	High performance self-hosted photo and video management solution	✅
ingress-nginx	Ingress-NGINX Controller for Kubernetes	✅
it-tools	Collection of handy online tools for developers	✅
kube-prometheus-stack	kube-prometheus-stack collects Kubernetes manifests, Grafana dashboards, and Prometheus rules combined with documentation and scripts to provide easy to operate end-to-end Kubernetes cluster monitoring with Prometheus using the Prometheus Operator	✅
loki	Like Prometheus, but for logs	✅
longhorn	Cloud-Native distributed storage built on and for Kubernetes	✅
maybe	The OS for your personal finances	❌
mealie	Recipe manager and meal planner	✅
metallb	A network load-balancer implementation for Kubernetes using standard routing protocols	✅
metrics-server	Scalable and efficient source of container resource metrics for Kubernetes built-in autoscaling pipelines	❌
mosquitto	Open source MQTT broker	✅
nextcloud	A safe home for all your data	✅
oauth2-proxy	A reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers	✅
opencloud	Excellent file sharing	✅
opentelemetry-collector	Vendor-agnostic implementation on how to receive, process and export telemetry data	✅
opentelemetry-operator	Kubernetes Operator for OpenTelemetry Collector	✅
paperless-ngx	Scan, index and archive all your physical documents	✅
reloader	A Kubernetes controller to watch changes in ConfigMap and Secrets and do rolling upgrades on Pods with their associated Deployment, StatefulSet, DaemonSet and DeploymentConfig	✅
satisfactory-server	Satisfactory server	✅
snapshot-controller	Implements the control loop for CSI snapshot functionality	✅
tailscale-operator	A Kubernetes Operator for Tailscale	✅
vaultwarden	Unofficial Bitwarden compatible server written in Rust	✅
velero	Backup and migrate Kubernetes applications and their persistent volumes	✅
zigbee2mqtt	Zigbee to MQTT bridge	✅

🏗️ k0s quick install

The install assumes that all external secrets are already created in a GitLab project as CI/CD variables.

Start the k0s cluster:

cd ~/homelab-gitops
sudo k0s install controller --enable-worker -c ./k0s.yaml
sudo k0s start
sleep 5
sudo k0s status
sudo k0s kubeconfig admin > ~/.kube/config
kubectl taint nodes --all node-role.kubernetes.io/master-

Create the GitLab token secret used by external-secrets:

kubectl create ns external-secrets
kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: gitlab-secret
  namespace: external-secrets
type: Opaque
stringData:
  token: xxx

Change the token value and type <Ctrl+D> <Enter> to create the secret.

Deploy external-secrets and ArgoCD apps:

cd ../../k8s-apps/external-secrets && helm dependency update && helm template external-secrets -n external-secrets . | kubectl apply -n external-secrets -f -
kubectl create ns argocd
cd ../../k8s-apps/argocd && helm dependency update && helm template argocd . -n argocd | kubectl apply -n argocd -f -
kubectl apply -f ../../argocd-apps/app-of-apps.yaml -n argocd

Cluster should be ready!

💣 Teardown

Save the GitLab token secret

kubectl get secret -n external-secrets gitlab-secret -o yaml > gitlab-secret.yaml

Teardown the cluster

sudo k0s stop
sudo k0s reset -v -d