GitOps Kubernetes Homelab

A fully GitOps-managed Kubernetes homelab running on Talos Linux and deployed with ArgoCD. This repository contains all cluster configurations and application deployments, enabling complete infrastructure-as-code management with automated reconciliation.

Architecture

Cluster Platform: Talos Linux with Omni management GitOps Engine: ArgoCD (self-managing) Storage: Longhorn distributed block storage Networking: MetalLB load balancer, NGINX Ingress DNS & Certificates: External-DNS + cert-manager with Cloudflare integration

Applications are organized into ArgoCD projects:

• setup - Core infrastructure components
  • Definitions: argocd/applications/setup
  • Configs: configs/setup/
• external - Public-facing applications
  • Definitions: argocd/applications/external
  • Configs: configs/external/
• internal - Internal-only services
  • Definitions: argocd/applications/internal
  • Configs: configs/internal/
• private - Private applications (separate repository)

Applications

• app-of-apps - Automated discovery of other Applications

Setup Infrastructure

• argocd - GitOps continuous delivery
• cert-manager - Automated certificate management with Let's Encrypt
• external-dns - Automated DNS record management via Cloudflare
• external-secrets - External secret management integration
• k8s-gateway - DNS gateway for ingress resources
• longhorn - Distributed block storage
• metallb - Bare metal load balancer
• metrics-server - Resource metrics collection
• nginx-ingress - Ingress controller
• sealed-secrets - Encrypted secrets management

External Services

• contact-api - Website contact form API
• harbor - Container registry
• home-assistant - Home automation platform
• main-site - Personal website
• minio - S3-compatible object storage
• seafile - File sync and share platform

Internal Services

• bazarr - Subtitle management for Radarr/Sonarr
• nzbget - Usenet downloader
• paperless - Document management system
• radarr - Movie collection manager
• shinobi - Video surveillance platform
• smtp - SMTP relay service
• sonarr - TV series collection manager
• tdarr - Media transcoding automation

Cluster Provisioning

The cluster runs on Talos Linux and is managed via Omni. Cluster configuration and machine provisioning is defined in omni/cluster.yaml.

Key cluster/lab features:

• Talos Linux v1.11.6
• Kubernetes v1.34.1
• Omni/Proxmox automatic node provisioner
• Longhorn distributed storage

Bootstrapping ArgoCD

After cluster provisioning, bootstrap ArgoCD to enable GitOps management:

kubectl apply -k configs/setup/argocd/
kubectl apply -f argocd/app-of-apps.yaml -n argocd

This deploys ArgoCD and the app-of-apps pattern, which automatically discovers all applications in this repository. Before the ArgoCD UI becomes accessible, critical infrastructure applications must be synced using the ArgoCD CLI in core mode:

# Switch to argocd namespace
kubectl config set-context --current --namespace=argocd

# Sync critical infrastructure components
argocd app sync metallb --core
argocd app sync nginx-ingress --core
argocd app sync cert-manager --core
argocd app sync external-secrets --core

Once these core components are deployed, the ArgoCD UI becomes accessible. Remaining applications can be reviewed and synced through the UI. ArgoCD becomes self-managing - any configuration changes are automatically reconciled.

Secret Management

This repository uses a two-tier secret management strategy:

1. Bootstrap Secrets - sealed-secrets is used only for initial cluster bootstrapping and ArgoCD setup
2. Runtime Secrets - external-secrets handles all application secrets after bootstrapping, integrating with external secret providers

Note: Sealed secrets in this repository are encrypted for this specific cluster. To use this configuration in your own environment, deploy sealed-secrets with your own keys and configure external-secrets for your secret backend.

Repository Structure

.
├── argocd/
│   ├── app-of-apps.yaml            # Root ArgoCD application
│   ├── applications/               # ArgoCD app definitions
│   │   ├── setup/                  # Infrastructure apps
│   │   ├── external/               # Public-facing apps
│   │   └── internal/               # Internal apps
│   └── projects/                   # ArgoCD project definitions
│       ├── setup.yaml              # Infrastructure project
│       ├── external.yaml           # External apps project
│       ├── internal.yaml           # Internal apps project
│       └── private.yaml            # Private apps project
├── configs/
│   ├── setup/                      # Infrastructure configurations
│   ├── external/                   # External app configurations
│   └── internal/                   # Internal app configurations
├── omni/
│   ├── cluster.yaml                # Talos cluster definition (Omni)
│   ├── omni/                       # Self-hosted Omni setup
│   │   └── compose.yaml            # Omni on-prem deployment
│   └── proxmox-provider/           # Proxmox infrastructure provider
│       ├── compose.yaml            # Provider service
│       ├── config.yaml             # Proxmox configuration
│       └── machineclass.yaml       # Machine class definitions
└── hack/                           # Helper scripts
    ├── download-helm-chart.sh      # Download Helm charts
    └── bump-chart-version.sh       # Update chart versions