A pragmatic Argo CD setup — GitOps that survives contact with reality

Argo CD is one of those projects that's wildly popular and wildly mis-deployed. Every team I work with has some version of Argo CD running. Maybe a third of them have it set up in a way that's actually saving them effort instead of being a worse version of kubectl apply with extra YAML.

The difference is usually in three places: repo structure, sync wave orchestration, and how you handle secrets.

The App-of-Apps repo layout

gitops-repo/
├── bootstrap/                  # root app-of-apps
├── platform/                   # cluster-wide infra (ingress, cert-manager, …)
├── tenants/
│   ├── team-payments/{dev,staging,prod}/
│   └── team-search/{dev,staging,prod}/
└── projects/                   # AppProject RBAC boundaries

A single root Application bootstraps the cluster. platform/ is owned by the platform team. Each tenant has its own folder per environment, so promotion is a PR that copies manifests one directory over.

The full write-up covers:

• Sync waves — the wave-numbering convention we use across every cluster
• Why we run External Secrets Operator + a vault, not sealed-secrets (rotation)
• Auto-sync for dev/staging, manual sync for prod (and why)
• ApplicationSet for fleet-of-environments patterns
• Notifications: the Slack alerts that actually matter
• Backing up Argo CD and the lessons from the time we didn't

We ship this layout on every managed Kubernetes cluster.