Overview

This guide explains our homelab Kubernetes setup, designed to help IT admins understand, run, and maintain the system.

Core Design Principles

1. GitOps as Source of Truth

   • All cluster states live in this Git repo
   • ArgoCD syncs cluster state with Git definitions
   • Changes require Git commits for audit tracking

2. Declarative Configuration

   • Uses Kubernetes YAML, Kustomize, and Terraform
   • Tools manage state based on defined specs

3. Automated Operations

   • ArgoCD ApplicationSets handle deployments
   • Cert-Manager runs certificate lifecycle
   • CI/CD pipelines automate testing and deployment

4. Security First

   • Non-root container execution
   • Network policies control traffic
   • External secrets management
   • Regular security scans

5. Clean Organization

   • Kustomize manages configurations
   • ArgoCD projects group related apps
   • ApplicationSets simplify scaling

Documentation Map

Cluster Setup

• Provision Talos Kubernetes
  • OpenTofu-based Talos deployment on Proxmox
  • Infrastructure setup steps

Kubernetes Management

• GitOps Configuration
  • ArgoCD setup and usage
  • Manifest structure
  • Service management

Application Guides

• Deploy Apps
  • User application deployment
  • App lifecycle management

Infrastructure

• Core Services
  • Network setup
  • Storage configuration
  • Auth systems
  • Monitoring stack

CI/CD

• Pipeline Configuration
  • CI/CD workflow setup
  • Dependabot settings
  • Repo maintenance