Argo CD ApplicationSets: Managing Many Clusters Without Copy-Paste
Twenty-three clusters, one app, and a folder of near-identical Application YAMLs that drifted constantly. ApplicationSets killed the copy-paste and the drift.
Key takeaways
- An Argo CD ApplicationSet generates one Application per cluster from a single template, so you stop copying Application YAML.
- Use the cluster generator with a label selector on cluster Secrets, add the matrix generator for app-by-cluster grids, and enable RollingSync progressive syncs so changes reach canary clusters before the whole fleet.
On this page
To deploy one app to many clusters in Argo CD, replace per-cluster Application files with one ApplicationSet using the cluster generator: it stamps out an Application for every registered cluster whose Secret matches a label. Add the matrix generator for addon-by-cluster grids, set preserveResourcesOnDeletion while refactoring, and roll out with RollingSync.
Verified against
Argo CD 3.5 (3.5.6, released 2026-10-20), against the Argo CD ApplicationSet docs for the cluster and matrix generators, Progressive Syncs, and Application deletion. Checked October 2026.
Picture the setup this replaces: a platform-agent DaemonSet that must run on every cluster you operate, say 23 of them across three regions plus a rotating set of ephemeral preview clusters. Each cluster has its own Application manifest in Git. Bumping the agent image means touching 23 files, and sooner or later two get missed and a stale agent version surfaces weeks later in an incident review. That copy-paste drift is exactly what ApplicationSets remove.
One generator, N Applications
An ApplicationSet is a controller that templates out Application resources from a generator. The cluster generator is the obvious starting point: it produces one Application per cluster registered in Argo CD (each remote cluster is a Secret labeled argocd.argoproj.io/secret-type: cluster), filtered by a selector on that Secret's labels.
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: platform-agent
namespace: argocd
spec:
goTemplate: true
generators:
- clusters:
selector:
matchLabels:
agent: enabled
template:
metadata:
name: 'agent-{{.nameNormalized}}'
labels:
env: '{{index .metadata.labels "env"}}'
spec:
project: platform
source:
repoURL: https://github.com/acme/platform-charts
targetRevision: main
path: charts/agent
helm:
valueFiles:
- 'values-{{.metadata.labels.region}}.yaml'
destination:
server: '{{.server}}'
namespace: platform-system
syncPolicy:
automated:
prune: true
selfHeal: true
Now the set of managed clusters is driven by a label on the cluster secret. Add agent: enabled to a new cluster's secret and the controller generates the Application on its next reconcile. Remove the label and the generator stops producing that entry, so the ApplicationSet deletes the Application; the resources-finalizer.argocd.argoproj.io finalizer it adds then cleans up the workloads on that cluster. Note that the prune: true in the template is a different thing: it removes resources that disappear from Git within a live Application.
We use {{.nameNormalized}} rather than {{.name}} in the Application name because cluster names often contain characters that are not valid in a Kubernetes resource name. The docs expose both.
Region-specific values without forking the chart
Notice values-{{.metadata.labels.region}}.yaml. Each cluster secret carries a region label (us-east, eu-west, ap-south), and the template picks the matching values file. That's how we handle the real-world truth that clusters are not identical: eu-west needs a lower memory limit, ap-south points at a regional mirror registry. One chart, per-region overrides, zero forked manifests.
Matrix generator for the harder cases
The cluster generator alone stops being enough when you deploy several apps to several clusters and the combinations matter. The matrix generator takes the Cartesian product of two generators. We use it to deploy a list of infra addons (defined in a Git directory) across the same labeled clusters:
# apps/platform-addons-appset.yaml (generators block)
generators:
- matrix:
generators:
- git:
repoURL: https://github.com/acme/platform-charts
revision: main
directories:
- path: addons/*
- clusters:
selector:
matchLabels:
agent: enabled
The git generator yields one entry per directory under addons/ (say cert-manager, node-exporter, fluent-bit), the cluster generator yields the clusters, and the matrix produces one Application per pair. Adding a new addon is a new directory; adding a cluster is a label. Neither requires editing the ApplicationSet.
The guardrails you actually need
Two settings save you from a bad afternoon. The first is preserveResourcesOnDeletion. By default, deleting the ApplicationSet cascades: its child Applications are deleted, and their finalizers delete the deployed resources on every cluster. If you're refactoring the ApplicationSet itself, that's terrifying. With this flag set, the controller does not add the finalizer to generated Applications, so workloads survive. Set it while you experiment:
# apps/platform-agent-appset.yaml (excerpt)
spec:
syncPolicy:
preserveResourcesOnDeletion: true
The second is progressive sync (strategy: RollingSync), which rolls changes out group by group instead of hitting all 23 clusters at once. Two details trip people up. First, it is a Beta feature (since Argo CD 3.3) and is off by default: enable it with --enable-progressive-syncs on the ApplicationSet controller or applicationsetcontroller.enable.progressive.syncs: "true" in argocd-cmd-params-cm. Second, the matchExpressions match labels on the generated Applications, not on the cluster Secrets. That is why the template above copies the cluster's env label onto each Application.
# apps/platform-agent-appset.yaml (excerpt)
spec:
strategy:
type: RollingSync
rollingSync:
steps:
- matchExpressions:
- key: env
operator: In
values: [canary]
- matchExpressions:
- key: env
operator: In
values: [prod]
Canary syncs first; the next step waits for those Applications to be healthy. A bad image bump now hits the canary group, not the fleet.
What still bites
Templating errors are opaque. A typo in a Go template field can render an Application with an empty path, and Argo happily tries to sync nothing, or worse, the repo root. Inspect what the generator produced before trusting a sync:
argocd appset get platform-agent
kubectl -n argocd get applications -l env=canary
argocd app diff agent-prod-eu-west-1
The cluster generator also only sees clusters Argo already knows about, so cluster registration has to happen first, usually via Terraform or a cluster-bootstrap job. And the in-cluster (local) cluster has no Secret by default, so a label selector silently excludes it until you create one. When a generated app sits OutOfSync anyway, the usual suspects are covered in Argo CD app OutOfSync. If GitOps itself is new to your team, GitOps explained covers the model ApplicationSets build on.
Questions people ask
How do I deploy one app to multiple clusters with Argo CD?
Register each cluster with Argo CD (argocd cluster add or a declarative cluster Secret), label the Secrets you want, then create an ApplicationSet with a cluster generator whose selector.matchLabels matches that label. The template's destination.server uses {{.server}}, so each cluster gets its own Application. New clusters join by gaining the label; no YAML is copied.
What is the difference between the cluster and matrix generators?
The cluster generator emits one parameter set per matching registered cluster. The matrix generator combines two child generators and emits their Cartesian product, for example every addon directory from a git generator times every labeled cluster. Use the cluster generator for one app across the fleet, and matrix only when you genuinely have a grid of apps by clusters.
Does deleting an ApplicationSet delete the deployed resources?
Yes, by default. The ApplicationSet's child Applications are deleted through owner references, and each Application's resources-finalizer.argocd.argoproj.io finalizer then removes its resources from the target cluster. Set spec.syncPolicy.preserveResourcesOnDeletion: true to stop the finalizer being added, or delete with kubectl delete applicationset NAME --cascade=orphan to keep the Applications.
The call we'd make
If you manage more than a handful of clusters and find yourself copying Application YAML, switch to ApplicationSets now, starting with the cluster generator plus per-region values files. Add the matrix generator only when you have a genuine app-times-cluster grid. And enable RollingSync before you point it at production, because "sync all 23 at once" is a great way to learn what a fleet-wide outage feels like.
Sources
Cite this article
Kiril Urbonas (2026). Argo CD ApplicationSets: Managing Many Clusters Without Copy-Paste. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/argo-cd-applicationsets-many-clusters
[Argo CD ApplicationSets: Managing Many Clusters Without Copy-Paste](https://www.devopsness.com/blog/argo-cd-applicationsets-many-clusters) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)
More from DevOps
Explore more articles in this category
KYAML: Kubernetes YAML Without the Norway Problem
Kubernetes is promoting KYAML, a strict subset of YAML that any parser accepts. It kills type coercion and indentation bugs without a migration.
GitHub Actions Pricing and Minute Optimization
How GitHub Actions billing actually works in 2026, why one macOS matrix leg can dominate the bill, and the YAML changes that move the number.
Helm Chart Anti-Patterns We've Stopped Using
Helm gives you a lot of rope. The patterns we used that backfired, the ones we replaced them with, and what to skip if you're starting today.
You might have missed
Evergreen posts worth revisiting.