talos-argocd-proxmox

A production-grade GitOps Kubernetes cluster running on Talos OS with self-managing ArgoCD. ArgoCD manages its own configuration and discovers applications by directory structure — no manual Application manifests needed.

Source repository: mitchross/talos-argocd-proxmox

This site is the rendered version of docs/ from that repo. Pages link back to source files (✏️ edit icon, top right) for one-click PRs.

[!IMPORTANT] Current pvc-plumber state (2026-06-01): - v4.0.1 live (permissive controller — not an admission gate) - 24 PVCs / 18 namespaces managed - 24/24 DR_COMPLETE - Kyverno not in the backup path - CNPG native / Barman → S3 - PostHog backup-exempt · redis-instance backup-exempt - migration campaign closed — no remaining candidates

Stack

• OS: Talos Linux on Proxmox VMs, provisioned via Omni / Sidero
• CNI: Cilium with Gateway API + LoadBalancer
• GitOps: ArgoCD (self-managing) + ApplicationSets for auto-discovery
• Storage: Longhorn (RWO block) + TrueNAS/RustFS (Kopia repository on S3)
• Backup: VolSync + Kopia, wired by pvc-plumber v4 (a permissive PVC-watching controller)
• Database: CloudNativePG (Postgres) with Barman backups to RustFS S3
• Secrets: 1Password Connect + External Secrets Operator
• Observability: kube-prometheus-stack, Loki, Tempo, OpenTelemetry, Grafana
• AI: llama-cpp (Qwen3.6-35B-A3B multimodal) on dedicated GPU

Documentation

🚀 Start here (pvc-plumber)

1. pvc-plumber-start-here — visual intro: what it is, the architecture, what it does NOT do, v4-vs-v5.
2. pvc-plumber-cheatsheet — one-page poster.
3. pvc-plumber-dynamic-workflow — how the operator thinks (decision trees, /audit actions).
4. talos-argocd-pvc-plumber-integration — how this repo uses it (add-a-PVC checklist, labels).

🛠️ Operate the platform

• volsync-storage-recovery — PVC backup/restore single source of truth + restore-drill runbook.
• kopia-maintenance-plan — repository maintenance (healthy; manual full not needed).
• storage-architecture-future — Longhorn-vs-restore-DR tiering (future idea).
• storage-model-rwo-rwx-and-sizing — RWO/RWX decision rule, truenas-csi vs static drivers, per-cluster class map, BigTank sizing.
• pvc-plumber-v4-cutover — day-of cutover runbook (label model, ownership, rollback).
• pvc-plumber-v4-migration-readiness — per-PVC migration status (campaign closed).
• cluster-dr-nuke-restore-runbook — full cluster rebuild/restore runbook.

Bootstrap rules from the full nuke

• CRDs first, controllers/apps second, CRs third.
• Observability is optional. Core apps must bootstrap without Prometheus.
• Do not install Prometheus Operator CRDs early to satisfy bootstrap apps.
• kube-prometheus-stack remains the sole owner of monitoring.coreos.com CRDs.

📐 Design / PRD

• pvc-plumber-v4-prd — locked design + §0 canonical status (shipped vs design).
• pvc-plumber-v4-roadmap — post-PRD backlog.
• pvc-plumber-v5-kopia-native-future — v5 fork (VolSync-strict vs Kopia-native) — parked, not built.
• multicluster-prd — multicluster design.

🗃️ Other domains

• Databases: cnpg-disaster-recovery · cnpg-explained
• GitOps / ArgoCD: argocd · argocd-entrypoints
• Networking: network-topology · network-policy
• Storage: rustfs-credential-runbook · kopia-maintenance-plan · storage-architecture-future
• Multicluster: prd · handoff notes
• Observability: radar-ng-observability
• AI / GPU: ai-model-catalog · 3090-llm-optimization

🗄️ Archive (historical only)

Historical migration, incident, design, and presentation docs live under archive/ — preserved for context, not current runbooks. Older research and plans remain under research/ and plans/ (also historical).

How to read these docs

• Start with the pvc-plumber visual docs for the current operator model.
• Use the storage recovery page for application PVC operations.
• Use the CNPG DR page only for CNPG recovery.
• Use the nuke runbook only for full rebuild planning.
• Treat archive/, research/, and plans/ as historical context.

Adopting any of this

This is one operator's homelab, not a product. The patterns are portable, but the specific image tags, hostnames, and 1Password item names are not. Start with VolSync storage recovery and Talos ArgoCD pvc-plumber integration.