# Argo CD ApplicationSets: Managing Many Clusters Without Copy-Paste

URL: https://www.devopsness.com/blog/argo-cd-applicationsets-many-clusters
Author: Kiril Urbonas
Published: 2026-06-29
Updated: 2026-10-31
Categories: DevOps
Tags: Argo CD, GitOps, Kubernetes, Deployment, Automation

Summary: Twenty-three clusters, one app, and a folder of near-identical Application YAMLs that drifted constantly. ApplicationSets killed the copy-paste and the drift.

---
# Argo CD ApplicationSets: Managing Many Clusters Without Copy-Paste

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]
> 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.

```yaml
# apps/platform-agent-appset.yaml
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:

```yaml
# 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:

```yaml
# 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.

```yaml
# 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](/blog/argo-cd-app-outofsync). If GitOps itself is new to your team, [GitOps explained](/blog/gitops-explained-introduction) 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

- [Argo CD Docs: Cluster generator](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators-Cluster/)
- [Argo CD Docs: Matrix generator](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators-Matrix/)
- [Argo CD Docs: ApplicationSet Progressive Syncs](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Progressive-Syncs/)
- [Argo CD Docs: Application deletion in ApplicationSets](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Application-Deletion/)

