$ show khuedoan/homelab
Khue's Homelab is a GitOps-driven infrastructure-as-code framework that automates a complete self-hosted Kubernetes platform from bare metal to user-facing applications. The codebase is organized into five layers: metal (Ansible roles that PXE-boot Fedora Server, bootstrap a k3s cluster with kube-vip HA, and install Cilium for networking/load balancing), system (bootstrap Helm charts for ArgoCD, cert-manager, ingress-nginx, Rook Ceph, and monitoring), platform (Gitea, Woodpecker CI, Grafana, Kanidm identity, Dex SSO, zot container registry), apps (Jellyfin + the *arr stack, Matrix, Paperless, Ollama, and more), and external (Terraform-managed Cloudflare DNS, tunnel, and ntfy alerting). ArgoCD ApplicationSets watch the git repository and deploy every Helm chart, making the repo itself the source of truth; a single top-level `make` drives the entire pipeline. The project demonstrates strong IaC craftsmanship: idempotent Ansible roles with checksum-verified downloads and run_once state handling (k3s token genesis, kubeconfig extraction), an ephemeral PXE server with per-MAC kickstart files and DHCP-proxy mode, declarative random secret generation via a small Go tool combined with the External Secrets Operator for cross-namespace secret sync, and a Terraform module that creates least-privilege Cloudflare API tokens injected directly into the cluster. It also includes a Nix dev shell for reproducible tooling, pre-commit hooks, Woodpecker CI that renders Helm diffs on pull requests, and Terratest-based smoke/integration/version tests. The author explicitly labels the project ALPHA and recommends forking for personal use. It is best treated as a reference architecture and a collection of reusable provisioning patterns rather than a turnkey product; some portions (scripts/hacks, take-screenshots, the gitea config job) are acknowledged work-in-progress, and a few pinned versions lag the ecosystem (Go 1.19 in-cluster compile jobs, k3s 1.30, several stale container image tags).
The LLM identified 6 files worth highlighting for reuse:
Self-contained Ansible role that bootstraps a multi-node k3s cluster: downloads a checksum-verified binary, generates a shared cluster token on the first master (run_once), distributes it to all nodes, renders server/agent configs, deploys kube-vip as a static pod for control-plane HA and load balancing, and extracts a kubeconfig rewritten with the correct external API address. Demonstrates a clean stateful-bootstrap pattern with idempotency guards that transfers to any lightweight Kubernetes distribution.
Ansible role that stands up an ephemeral PXE boot server from a Fedora DVD ISO: downloads the ISO with checksum verification, extracts it with xorriso, runs dnsmasq in configurable DHCP-proxy mode with UEFI PXE boot, and renders a per-MAC kickstart file for unattended OS installation with static networking and a raw partition carved out for Ceph. A reusable pattern for network-based bare-metal provisioning that requires no standing infrastructure.
Standalone Python script that clones two git branches into temp directories, detects changed Helm charts under a given subpath, renders each with `helm template`, and produces a dyff between target and source. Purpose-built for pull-request review of GitOps Helm changes; fully parameterized and dependency-light, so it drops into any CI pipeline for rendering-before-approval workflows.
Python CLI that manages Restic-based PVC backups as Kubernetes custom resources. It creates or patches ExternalSecrets for S3 credentials and VolSync ReplicationSource/ReplicationDestination objects, with a --action setup|restore switch, templated secret rendering, and full create-or-patch idempotency. A solid backup-as-code pattern for stateful workloads that can be adapted to other CRD-driven backup operators.
Self-contained Jsonnet that transforms an Alertmanager webhook payload into a rich ntfy.sh notification: severity-to-emoji/priority mapping, resolved-state priority downgrade, and runbook URL action buttons. Solves the recurring alert-routing problem (Alertmanager webhook to consumer-friendly push notification) with a pure, testable transformation function that has zero coupling to the rest of the repository.
Small Go utility that reads a YAML spec of desired random secrets and idempotently creates or updates Kubernetes Secrets in a global-secrets namespace, generating new values only for keys that do not yet exist so re-runs never rotate or churn existing credentials. Demonstrates a clean declarative CRUD-loop pattern for secret bootstrap that can be extracted as a general Kubernetes secret-provisioning job or sidecar.