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.
This section provides a high level overview of the project. For further information, please see the documentation.
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.
The cluster is running on Debian based distributions, deployed on bare-metal. We use custom Ansible playbooks and roles to setup the Kubernetes cluster.
- 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.
| 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-3 | 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
- 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
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.
Cilium is configured with BGP control plane, both on my router and within the Kubernetes cluster.
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.grigri.cloud domain is used. Configured as:
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod-dns
external-dns.alpha.kubernetes.io/enabled: "true"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.cloudThanks 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.