🏠 HomeLab-2.0 💻

My personal homelab playground, stored as code.

The goal is to seamlessly bootstrap a Kubernetes cluster with all the bells and whistles
— from infrastructure to apps —
in one smooth, reproducible flow.
Aiming to keep things as lightweight and simple as possible, while still providing flexibility.

✨ Features

• 🚀 One-command cluster provisioning
  Provision and configure a full Kubernetes cluster with a single command: mise run up <env>

• 🔍 Automatic application discovery
  No need to manually define ArgoCD application manifests — applications are automatically detected and deployed.

• 🧰 One entrypoint to rule them all
  No more memorizing complex commands. All essential workflows are defined as Mise tasks—your single, consistent entrypoint for development.
  Run mise tasks to discover everything you need.

• ✅ Catch issues before they catch you
  Every commit runs automatic pre-commit checks that generate and lint your Kubernetes manifests against the API spec.
  So you catch mistakes early, not in production.

• 🛠️ Isolated development setup, zero headaches
  Work in an isolated, reproducible environment powered by Mise and Dev Containers
  so you always have the right tools, versions, and setup from day one.

• 🌍 Manage multiple environments effortlessly
  Build on a shared base with environment-specific overlays for clear separation and reproducibility.

• 🔐 Secret management made easy
  Secure your secrets with SOPS: encrypted, version-controlled, and stored right alongside your config.
  No external vaults, no guesswork.

🏛️ Foundation stack

This section describes the essential infrastructure components that form the backbone of the homelab environment.

• Infrastructure
  Terraform, Proxmox VE, TalosOS

• GitOps
  ArgoCD Kustomize Helm

• Networking
  Cilium CNI, MetalLB, Nginx Ingress Controller

• Storage
  Synology iSCSI & NFS

• Monitoring
  VictoriaLogs, Vector, VictoriaMetrics Grafana

• Security
  Cert-Manager, SOPS, Azure Key Vault, Trivy Planned

• Authentication
  Dex Planned

• Development
  Mise, Docker

🚀 Get up and running

How to deploy the entire cluster from the ground up.

1. Setup devcontainer.

   This will setup all the required tools needed for project development.

2. To provision and configure a full-blown cluster simply run:

   mise run up <env>

   This command will:

   1. Use Terraform to provision TalosOS machines on the Proxmox host and initialize the Kubernetes cluster.

   2. Deploy ArgoCD using the bootstrap configuration to enable GitOps workflows.

   3. Automatically discover and deploy all applications defined in the apps/ directory through ArgoCD ApplicationSets.

3. Good to go 🎉

   The Kubeconfig and Talosconfig files are automaticalled fetched and stored in .config directory and your shell is configured automatically.

   You can now interact with the cluster: kubectl get pods -A

📂 Project structure

This repository follows a GitOps approach using ArgoCD for continuous deployment. The structure is organized as follows:

• .lint/: Linting configurations

• .mise/: Mise configurations

  • tasks: Reusable scripts for cluster management, provisioning, and automation.

• apps/: Contains all applications deployed to the cluster

  • Organized in <env>/<project>/<namespace>/<app> structure
  • Each app contains its kustomization.yaml and configurations
  • Namespaces are created automatically during deployment

• bootstrap/: Contains initial cluster setup and ArgoCD configuration

  • projects/: Contains ArgoCD project definitions
  • resources/: Essential cluster-wide resources
  • misc/: Miscellaneous bootstrap configurations

• provision/: Contains Terraform infrastructure provisioning scripts and configurations

  • core/: Core Terraform modules and scripts for cluster provisioning
  • <env>/: Environment-specific Terraform variable files (e.g., dev/, prd/)

📝 To do

This section outlines a list of planned improvements and upcoming features, presented in no particular order.

• Investigate Cilium load balancer IPAM as al alternative for Metallb.

• Investigate Cillum Gateway API as an alternative for Nginx ingress controller.

• Implement Dex IdP.

• Refactor ArgoCD config management plugin script.

• Setup alerting rules and channels.

• Deploy Trivy Operator.

• Checkout Sidero Omni.

• Implement KRR