A personal homelab setup using Kubernetes (K3s), Helmfile, and GitOps practices for automated infrastructure management.
This repository manages a personal homelab running on Kubernetes (K3s), using Helmfile to deploy services and Ansible to provision bare-metal nodes. Secrets are encrypted with SOPS, and ArgoCD handles GitOps delivery.
This project is the cornerstone of a homelab — it provides the base infrastructure (cluster, networking, monitoring, identity). If you want to deploy your own applications (a portfolio site, a blog, custom services, etc.), those should live in a separate repository and be deployed on top of this foundation. This keeps the infrastructure clean and your application deployments independent.
The homelab follows a layered architecture:
- Infrastructure Layer: K3s cluster provisioned with Ansible
- Platform Layer: Core services (MetalLB, Traefik, cert-manager) for networking and certificates
- Application Layer: Applications deployed via Helmfile (ArgoCD, Authentik, Grafana, etc.)
- Observability Layer: Monitoring (Prometheus), Logging (Loki), Tracing (Tempo), and Profiling (Pyroscope)
| Service | Purpose | Namespace |
|---|---|---|
| prometheus-operator-crds | Prometheus Operator CRDs | monitoring-system |
| cert-manager | SSL/TLS certificate management | cert-manager-system |
| cert-manager-config | Certificate configuration | cert-manager-system |
| external-dns | DNS management with Cloudflare | cert-manager-system |
| authentik-blueprints | Declarative provider/app/user provisioning | auth-system |
| longhorn | Distributed block storage | longhorn-system |
| metallb | Load balancer for bare metal | lb-system |
| metallb-config | MetalLB IP Address Pool and L2 Advertisement | lb-system |
| prometheus-stack | Monitoring and alerting | monitoring-system |
| grafana | Metrics visualization | monitoring-system |
| loki | Log aggregation | monitoring-system |
| alloy | OpenTelemetry collector (logs, traces, profiling) | monitoring-system |
| tempo | Distributed tracing | monitoring-system |
| pyroscope | Continuous profiling | monitoring-system |
| traefik | Reverse proxy and ingress | ingress-system |
| authentik | Identity provider | auth-system |
| argocd | GitOps continuous delivery | gitops-system |
| authentik-ingress | Authentik ingress configuration | auth-system |
| Tool | Purpose |
|---|---|
| K3s | Lightweight Kubernetes distribution |
| Ansible | Cluster provisioning and configuration |
| Helmfile | Helm releases management |
| Helm | Kubernetes package manager |
| ArgoCD | GitOps continuous delivery |
| SOPS | Secrets encryption |
| Prometheus | Monitoring and alerting |
| Grafana | Metrics visualization |
| Loki | Log aggregation |
| Tempo | Distributed tracing |
| Pyroscope | Continuous profiling |
| Grafana Alloy | OpenTelemetry collector for logs, traces, and eBPF profiling |
| Longhorn | Cloud-native distributed block storage |
| MetalLB | Load balancer for bare metal Kubernetes |
| Traefik | Cloud-native reverse proxy |
| cert-manager | X.509 certificate management |
| external-dns | Synchronize exposed services with DNS providers |
| Authentik | Identity provider |
| Cloudflare | DNS and CDN provider |
| pre-commit | Git hooks for code quality |
| ansible-lint | Ansible playbook linting |
homelab/
├── charts/ # Custom Helm charts
│ ├── cert-manager-config/ # Certificate configuration
│ ├── external-ingress/ # Ingress definitions
│ └── metallb-config/ # MetalLB configuration
├── docs/ # Documentation
├── helmfile/ # Helmfile configuration
│ ├── common/ # Common values and templates
│ │ ├── values/ # Service values files
│ │ └── common.yaml.gotmpl # Main releases definition
│ ├── environments/ # Environment-specific configs
│ │ ├── dev/ # Development environment
│ │ │ ├── secrets/ # Per-chart encrypted secrets
│ │ │ └── values/ # Per-chart value overrides
│ │ └── prod/ # Production environment
│ │ ├── secrets/ # Per-chart encrypted secrets
│ │ └── values/ # Per-chart value overrides
│ ├── secret-templates/ # Secret templates with descriptions
│ └── locks/ # Helmfile lock files
├── metal/ # Bare metal provisioning
│ └── k3s/ # K3s cluster setup with Ansible
├── scripts/ # Utility scripts
├── helmfile.yaml.gotmpl # Main Helmfile entry point
├── ROADMAP.md # Project roadmap
└── README.md # This file
Fork this repository to store your own configs and secrets. See docs/FORKING.md for setup.
See docs/INSTALL.md for the full setup guide, including prerequisites, helm plugins, credentials, and step-by-step deployment.
# Quick start
./scripts/check-requirements.sh # verify tools
cp helmfile/config.template.yaml helmfile/environments/<env>/config.yaml # configure
./scripts/init-secrets.sh <env> # set up secrets
cd metal/k3s && ./run.sh # provision cluster
./scripts/install-helmfiles.sh <env> # deploy servicesSee docs/CONFIG.md for all available settings and docs/SECRETS.md for secrets management.
The homelab includes a comprehensive monitoring stack:
- Prometheus: Metrics collection and alerting
- Grafana: Visualization and dashboards
- Loki: Log aggregation
- Tempo: Distributed tracing
- Pyroscope: Continuous profiling
- Grafana Alloy: OpenTelemetry collector for logs, traces, and eBPF profiling
Grafana is exposed via MetalLB LoadBalancer. Access it using the external IP assigned by MetalLB.
- Kubernetes Cluster
- Node Exporter
- Kubernetes Pods
- MetalLB
- Longhorn
- CoreDNS
- External DNS
- Authentik
- ArgoCD Operations
- ArgoCD Application
- ArgoCD Notifications
- Roadmap — upcoming features and progress
- Testing — pre-commit hooks and ansible-lint
- Configuration — config system reference and all available settings
- Installation — step-by-step setup guide
- Forking — how to fork and maintain your own configs and secrets
- Architecture Decisions — ADRs documenting significant infrastructure changes
- Scripts — automation script documentation and usage
- Secrets — full secrets reference with criticality levels
See CONTRIBUTING.md. Every PR with a meaningful change must include an ADR.
This project is licensed under the MIT License - see the LICENSE file for details.
- K3s for the lightweight Kubernetes distribution
- Helmfile for Helm releases management
- ArgoCD for GitOps continuous delivery
- Grafana and the Grafana stack for observability
- Longhorn for cloud-native block storage
- MetalLB for bare metal load balancing
- Traefik for reverse proxy and ingress
- cert-manager for certificate management
- Authentik for identity management
- SOPS for secrets encryption
- Ansible for cluster provisioning
- Let's Encrypt for free TLS certificates
- Cloudflare for DNS and CDN services
This project does not authorize the use of its code, documentation, or any associated materials for training artificial intelligence (AI) or machine learning (ML) models. Any use of this repository's content for AI/ML training purposes is strictly prohibited without explicit written permission from the project owner.