# mitchross/talos-argocd-proxmox architecture

> Architecture diagram of the GitHub repository mitchross/talos-argocd-proxmox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mitchross/talos-argocd-proxmox
- Repository: https://github.com/mitchross/talos-argocd-proxmox

## Overview

This repository defines a Talos-on-Proxmox homelab Kubernetes cluster and its GitOps-managed services. The principal workflow is administrator-driven node provisioning through Omni, followed by one-time cluster bootstrap and Argo CD reconciliation of platform dependencies and discovered applications. Separate branches cover storage and zero-touch backups, ingress/networking, GPU workloads, and monitoring. Edges reflect README-described orchestration and configuration relationships; sampled source files are peripheral to the main cluster workflow, so implementation-level wiring not documented there is omitted.

Main entry points: [`infrastructure/controllers/argocd/apps/core-dependencies`](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/argocd/apps/core-dependencies) (Core Dependencies), [`infrastructure/controllers/argocd/root.yaml`](https://github.com/mitchross/talos-argocd-proxmox/blob/main/infrastructure/controllers/argocd/root.yaml) (Argo CD Root), [`infrastructure/controllers/argocd/apps/appsets`](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/argocd/apps/appsets) (ApplicationSets), [`infrastructure/controllers/kopiur-operator`](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/kopiur-operator) (Kopiur Operator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provisioning["Cluster Provisioning"]
  node_omni["Omni"]
  node_proxmox["Proxmox Provider"]
  node_talos["Talos Cluster"]
end

subgraph group_gitops["GitOps Reconciliation"]
  node_git[("Git Repository")]
  node_argocd["Argo CD Root<br/>[root.yaml]"]
  node_appsets["ApplicationSets"]
end

subgraph group_platform["Cluster Platform"]
  node_core["Core Dependencies"]
  node_cilium["Cilium Networking"]
  node_gateway["Gateway API"]
  node_gpu["GPU Support"]
end

subgraph group_protection["Storage &amp; Backups"]
  node_longhorn["Longhorn Storage"]
  node_kopiur["Kopiur Operator"]
  node_kopiurconfig["Backup Configuration"]
  node_rustfs["RustFS Storage"]
end

subgraph group_services["Workloads &amp; Observability"]
  node_myapps["User Applications"]
  node_monitoring["Monitoring Stack"]
  node_otel["OpenTelemetry"]
end

node_admin(("Administrator"))
node_nfs[("NAS Storage")]

node_admin -->|"provisions with"| node_omni
node_omni -->|"uses provider"| node_proxmox
node_omni -->|"provisions"| node_talos
node_admin -->|"bootstraps"| node_argocd
node_git -->|"provides configuration"| node_argocd
node_argocd -->|"creates"| node_appsets
node_argocd -->|"orders sync"| node_core
node_appsets -->|"discovers applications"| node_myapps
node_appsets -->|"discovers applications"| node_monitoring
node_appsets -->|"discovers applications"| node_gpu
node_core -->|"deploys"| node_cilium
node_core -->|"deploys"| node_longhorn
node_core -->|"deploys"| node_kopiur
node_core -->|"deploys"| node_gateway
node_kopiurconfig -->|"configures"| node_kopiur
node_kopiurconfig -->|"targets repository"| node_rustfs
node_kopiur -->|"restores volumes"| node_longhorn
node_kopiur -->|"backs up to"| node_nfs
node_argocd -->|"reconciles"| node_otel
node_otel -->|"exports telemetry"| node_monitoring
node_myapps -.->|"uses GPU support"| node_gpu

click node_omni "https://github.com/mitchross/talos-argocd-proxmox/tree/main/omni/omni"
click node_proxmox "https://github.com/mitchross/talos-argocd-proxmox/tree/main/omni/proxmox-providers"
click node_talos "https://github.com/mitchross/talos-argocd-proxmox/tree/main/omni/cluster-template"
click node_argocd "https://github.com/mitchross/talos-argocd-proxmox/blob/main/infrastructure/controllers/argocd/root.yaml"
click node_appsets "https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/argocd/apps/appsets"
click node_core "https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/argocd/apps/core-dependencies"
click node_cilium "https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/networking/cilium"
click node_gateway "https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/networking/gateway"
click node_gpu "https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/nvidia-gpu-operator"
click node_longhorn "https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/storage/longhorn"
click node_kopiur "https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/kopiur-operator"
click node_kopiurconfig "https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/kopiur"
click node_rustfs "https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/storage/rustfs-lifecycle"
click node_myapps "https://github.com/mitchross/talos-argocd-proxmox/tree/main/my-apps"
click node_monitoring "https://github.com/mitchross/talos-argocd-proxmox/tree/main/monitoring/prometheus-stack"
click node_otel "https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/opentelemetry-operator"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_omni,node_proxmox,node_talos toneBlue
class node_git,node_argocd,node_appsets,node_nfs toneAmber
class node_core,node_cilium,node_gateway,node_gpu toneMint
class node_longhorn,node_kopiur,node_kopiurconfig,node_rustfs toneRose
class node_myapps,node_monitoring,node_otel,node_admin toneIndigo
```

## Components

### Cluster Provisioning

- [Omni](https://github.com/mitchross/talos-argocd-proxmox/tree/main/omni/omni): `omni/omni`
- [Proxmox Provider](https://github.com/mitchross/talos-argocd-proxmox/tree/main/omni/proxmox-providers): `omni/proxmox-providers`
- [Talos Cluster](https://github.com/mitchross/talos-argocd-proxmox/tree/main/omni/cluster-template): `omni/cluster-template`

### GitOps Reconciliation

- **Git Repository**
- [Argo CD Root](https://github.com/mitchross/talos-argocd-proxmox/blob/main/infrastructure/controllers/argocd/root.yaml): `infrastructure/controllers/argocd/root.yaml`
- [ApplicationSets](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/argocd/apps/appsets): `infrastructure/controllers/argocd/apps/appsets`

### Cluster Platform

- [Core Dependencies](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/argocd/apps/core-dependencies): `infrastructure/controllers/argocd/apps/core-dependencies`
- [Cilium Networking](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/networking/cilium): `infrastructure/networking/cilium`
- [Gateway API](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/networking/gateway): `infrastructure/networking/gateway`
- [GPU Support](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/nvidia-gpu-operator): `infrastructure/controllers/nvidia-gpu-operator`

### Storage & Backups

- [Longhorn Storage](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/storage/longhorn): `infrastructure/storage/longhorn`
- [Kopiur Operator](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/kopiur-operator): `infrastructure/controllers/kopiur-operator`
- [Backup Configuration](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/kopiur): `infrastructure/controllers/kopiur`
- [RustFS Storage](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/storage/rustfs-lifecycle): `infrastructure/storage/rustfs-lifecycle`

### Workloads & Observability

- [User Applications](https://github.com/mitchross/talos-argocd-proxmox/tree/main/my-apps): `my-apps`
- [Monitoring Stack](https://github.com/mitchross/talos-argocd-proxmox/tree/main/monitoring/prometheus-stack): `monitoring/prometheus-stack`
- [OpenTelemetry](https://github.com/mitchross/talos-argocd-proxmox/tree/main/infrastructure/controllers/opentelemetry-operator): `infrastructure/controllers/opentelemetry-operator`

### Other components

- **Administrator**
- **NAS Storage**

## Connections

- Administrator → Omni: provisions with
- Omni → Proxmox Provider: uses provider
- Omni → Talos Cluster: provisions
- Administrator → Argo CD Root: bootstraps
- Git Repository → Argo CD Root: provides configuration
- Argo CD Root → ApplicationSets: creates
- Argo CD Root → Core Dependencies: orders sync
- ApplicationSets → User Applications: discovers applications
- ApplicationSets → Monitoring Stack: discovers applications
- ApplicationSets → GPU Support: discovers applications
- Core Dependencies → Cilium Networking: deploys
- Core Dependencies → Longhorn Storage: deploys
- Core Dependencies → Kopiur Operator: deploys
- Core Dependencies → Gateway API: deploys
- Backup Configuration → Kopiur Operator: configures
- Backup Configuration → RustFS Storage: targets repository
- Kopiur Operator → Longhorn Storage: restores volumes
- Kopiur Operator → NAS Storage: backs up to
- Argo CD Root → OpenTelemetry: reconciles
- OpenTelemetry → Monitoring Stack: exports telemetry
- User Applications → GPU Support: uses GPU support