¶ Core Components
¶ How ArgoCD Deploys the Cluster
The cluster uses an app-of-apps pattern: a single root ArgoCD Application points to the k8s-cluster-config Git repository. Inside that repo, each component has its own application.yaml. ArgoCD reads these and creates child Applications — one per component.
graph TB
GIT[Git Repo<br/>k8s-cluster-config]
ROOT[ArgoCD<br/>Root App]
A1[cert-manager app]
A2[metallb app]
A3[traefik app]
A4[longhorn app]
A5[vault app]
AN[all other apps]
GIT --> ROOT
ROOT -->|reads app-of-apps| A1
ROOT --> A2
ROOT --> A3
ROOT --> A4
ROOT --> A5
ROOT --> AN
A1 -->|deploys| H1[cert-manager Helm release]
A2 -->|deploys| H2[metallb Helm release]
A3 -->|deploys| H3[traefik Helm release]
Why app-of-apps? Each component is independently managed. You can sync, roll back, or pause a single component without touching others. ArgoCD tracks drift — if someone manually edits a K8s resource, ArgoCD detects the diff and can auto-heal it.
¶ Sync Wave Ordering
ArgoCD uses argocd.argoproj.io/sync-wave annotations to control deployment order. Lower waves deploy first and must become healthy before the next wave starts.
graph LR
W0[Wave -10<br/>CoreDNS custom]
W1[Wave 0<br/>cert-manager]
W2[Wave 1<br/>MetalLB]
W3[Wave 2<br/>Traefik]
W4[Wave 3<br/>CrowdSec + Storage + metrics-server]
W5[Wave 4-5<br/>Vault + VSO]
W6[Wave 6<br/>Velero + Technitium]
W7[Wave 7<br/>ExternalDNS]
W8[Wave 8<br/>Harbor]
W9[Wave 9-10<br/>Runners + Authentik]
W10[Wave 11-12<br/>Monitoring]
W11[Wave 13-14<br/>Apps]
W0 --> W1 --> W2 --> W3 --> W4 --> W5 --> W6 --> W7 --> W8 --> W9 --> W10 --> W11
Why this order? Each layer depends on the one before:
- DNS must work before anything else can resolve hostnames
- TLS certificates (cert-manager) needed before Traefik can terminate HTTPS
- Storage must exist before stateful apps can create PVCs
- Vault must be ready before VSO can sync secrets into namespaces
- Apps that need DNS records (via ExternalDNS) must deploy after it
¶ How Secrets Flow Into Pods
Every app that needs a secret follows the same pipeline:
graph LR
VAULT[Vault<br/>kv/secret/path]
VSO[Vault Secrets Operator<br/>VaultStaticSecret CR]
K8S[K8s Secret<br/>in app namespace]
POD[Pod<br/>env / volume mount]
VAULT -->|VSO reads on schedule| VSO
VSO -->|creates and syncs| K8S
K8S -->|mounted by| POD
- Vault stores the secret at a path like
kv/authentik/postgres - A VaultStaticSecret CR in the app namespace tells VSO what path to read and what K8s secret to create
- VSO polls Vault every 60s and updates the K8s secret if the value changes
- The Pod spec references the K8s secret — Kubernetes injects it as env vars or a mounted file
This means: to add a new secret to a pod, you never edit the pod spec directly. You write the value to Vault, create a VaultStaticSecret CR, and the secret appears automatically.
¶ Component Reference
All components are deployed via ArgoCD. Lower sync waves deploy first.
| Wave | Component | What It Does | Helm Chart | Version | Namespace |
|---|---|---|---|---|---|
| -10 | coredns-custom | Custom CoreDNS config (local DNS overrides) | (raw manifests) | — | kube-system |
| 0 | cert-manager | Automatically issues and renews TLS certificates (Let's Encrypt via ACME) | cert-manager |
1.18.2 | cert-manager |
| 1 | metallb | Assigns real IP addresses (192.168.88.12) to LoadBalancer Services | metallb |
0.15.2 | metallb-system |
| 2 | traefik | HTTP/HTTPS reverse proxy and ingress controller; terminates TLS | traefik |
34.4.1 | traefik |
| 3 | crowdsec | IDS/IPS and WAF: IP reputation (LAPI), per-request deep inspection (AppSec), community blocklist (CAPI); integrates with Traefik via bouncer plugin | crowdsec |
0.22.1 | crowdsec |
| 3 | longhorn | Distributed block storage using K8s node SSDs; provides longhorn (2-replica default) and longhorn-2rep StorageClasses |
longhorn |
1.10.0 | longhorn-system |
| 3 | nfs-synology | NFS provisioner for Synology HDD pool; provides nfs-synology StorageClass |
nfs-subdir-external-provisioner |
4.0.18 | nfs-storage |
| 3 | nfs-subdir-retain | NFS provisioner for TrueNAS NVMe (retain policy) | nfs-subdir-external-provisioner |
4.0.18 | nfs-storage |
| 3 | nfs-subdir-delete | NFS provisioner for TrueNAS NVMe (delete policy — ephemeral) | nfs-subdir-external-provisioner |
4.0.18 | nfs-storage |
| 3 | metrics-server | Provides kubectl top and HPA with CPU/memory usage data |
metrics-server |
3.13.0 | kube-system |
| 4 | vault | Secret store; single source of truth for all passwords and tokens | vault |
0.31.0 | vault |
| 5 | vso | Watches VaultStaticSecret CRs and syncs Vault values into K8s Secrets | vault-secrets-operator |
1.0.1 | vso-system |
| 5 | argocd-oidc | Configures ArgoCD to authenticate via Authentik SSO | (raw manifests) | — | argocd |
| 6 | velero | K8s backup: manifests + NFS PVC data via Kopia fs-backup to MinIO | velero |
8.3.0 | velero |
| 6 | technitium | Primary + secondary DNS servers with ad blocking, DoT/DoH, DNSSEC; serves cluster and home network | (raw manifests) | — | technitium |
| 7 | external-dns | Watches Ingress/Service objects and automatically creates Technitium DNS entries via rfc2136+TSIG | external-dns |
1.19.0 | external-dns |
| 8 | harbor | Private container registry with vulnerability scanning (Trivy) and signing (Cosign) | harbor |
1.18.0 | harbor |
| 8 | syncthing | P2P file sync: K8s pod reads TrueNAS NFS (Send Only) → Synology NAS (Receive Only + Ignore Deletes). Replicates Proxmox VM backups to Synology archive | (raw manifests) | — | syncthing |
| 9 | github-runners-controller | ARC controller that manages the GitHub Actions runner lifecycle | (ARC controller) | 0.12.1 | actions-runner-system |
| 10 | github-runners-scale-set | Self-hosted GHA runners that auto-scale based on queued jobs | (ARC runner set) | 0.12.1 | gha-runners |
| 10 | authentik | Identity Provider (IdP) and SSO gateway; all apps authenticate through it | authentik |
2025.10.3 | authentik |
| 11 | grafana | Dashboards UI for metrics, logs, and traces; authenticated via Authentik OIDC | grafana |
10.1.4 | monitoring |
| 11 | victoria-metrics | Time-series database (Prometheus-compatible); stores 90 days of metrics | victoria-metrics-single |
0.12.1 | monitoring |
| 11 | victoria-logs | Log storage backend; stores 30 days of pod stdout and MikroTik syslog | victoria-logs-single |
0.8.11 | monitoring |
| 11 | vmagent | Metrics scraper DaemonSet; collects from K8s, NAS, Proxmox, network gear | victoria-metrics-agent |
0.14.5 | monitoring |
| 11 | vmalert | Evaluates alerting rules against VictoriaMetrics; sends to Alertmanager | victoria-metrics-alert |
0.31.0 | monitoring |
| 11 | vector | Log collector DaemonSet; ships K8s pod logs and MikroTik syslog to VictoriaLogs | vector |
0.36.1 | monitoring |
| 11 | opentelemetry-collector | OTLP ingestion hub; routes traces → Tempo, metrics → VictoriaMetrics, logs → VictoriaLogs | opentelemetry-collector |
0.146.0 | monitoring |
| 11 | tempo | Distributed trace storage (Grafana Tempo); stores 14 days of traces in MinIO | tempo |
1.10.3 | monitoring |
| 12 | kube-state-metrics | Exposes K8s object state (pod health, PVC status, deployment replicas) as metrics | kube-state-metrics |
6.4.1 | monitoring |
| 13 | nas-ingress | Traefik IngressRoutes for NAS Docker apps (port-forwards to 192.168.88.19) | (raw manifests) | — | nas-ingress |
| 14 | nextcloud | Self-hosted file sync and collaboration (Dropbox/Google Drive alternative) | nextcloud |
8.9.0 | nextcloud |
¶ Sync Wave Strategy — Why Each Layer
graph TB
subgraph Wave -10
DNS0[CoreDNS custom<br/>DNS must work first]
end
subgraph Wave 0
TLS[cert-manager<br/>TLS before HTTPS]
end
subgraph Wave 1
LB[MetalLB<br/>IPs before Services]
end
subgraph Wave 2
ING[Traefik<br/>Ingress before apps]
end
subgraph Wave 3
STG[Storage and metrics-server<br/>PVCs before stateful apps]
end
subgraph Waves 4-5
SEC[Vault and VSO<br/>Secrets before apps read them]
end
subgraph Waves 6-7
BK[Velero backup and DNS services]
end
subgraph Wave 8
REG[Harbor<br/>Registry before CI/CD]
end
subgraph Waves 9-10
AUTH[Runners and Authentik<br/>Auth before apps need SSO]
end
subgraph Waves 11-12
MON[Full monitoring stack]
end
subgraph Waves 13-14
APP[Applications<br/>Everything else ready]
end
DNS0 --> TLS --> LB --> ING --> STG --> SEC --> BK --> REG --> AUTH --> MON --> APP
¶ Components with VSO Secrets
These components have resources/ directories in k8s-cluster-config containing VSO manifests (ServiceAccount + VaultAuth + VaultStaticSecret).
| Component | Namespace | Vault Path | K8s Secret Created |
|---|---|---|---|
authentik |
authentik | kv/authentik/* |
authentik-secret-key, authentik-db, etc. |
argocd-oidc |
argocd | kv/authentik/argocd-oidc |
argocd-oidc-secret |
grafana |
monitoring | kv/monitoring/grafana/* |
grafana-admin, grafana-oidc |
harbor |
harbor | kv/authentik/harbor-oidc |
harbor-oidc-secret |
nextcloud |
nextcloud | kv/nextcloud/admin |
nextcloud-admin |
technitium |
technitium | kv/technitium/admin |
technitium-admin |
external-dns |
external-dns | kv/external-dns/tsig |
technitium-tsig |
vmalert |
monitoring | kv/monitoring/alertmanager/ntfy |
alertmanager-ntfy |
velero |
velero | kv/velero/minio |
velero-minio-creds |
crowdsec |
crowdsec | kv/crowdsec/bouncer |
crowdsec-bouncer-key |
traefik (crowdsec bouncer key) |
traefik | kv/traefik/crowdsec-bouncer |
crowdsec-bouncer-key |
tempo |
monitoring | kv/monitoring/tempo/minio |
tempo-minio-creds |
vmalert (restore-test) |
monitoring | kv/monitoring/db-backup-minio |
restore-test-minio |