You have a fleet of Kubernetes clusters and the same set of platform tooling needs to land on each — Prometheus, cert-manager, ingress controller, secret operator, the lot. Authoring one Argo CD Application per cluster × per add-on quickly produces hundreds of manifests with copy-paste drift. ApplicationSet is the Argo CD CRD that templates Application resources from generators — cluster-aware, Git-aware, file-aware — and this article is the reference we use when designing one for a real fleet.
How to verify
The ApplicationSet controller should be running:
kubectl -n argocd get deploy argocd-applicationset-controller
An ApplicationSet should produce one or more Applications:
kubectl -n argocd get appset
kubectl -n argocd get app -l app.kubernetes.io/instance=<appset-name>
Generator output can be inspected by examining the Applications it created:
kubectl -n argocd describe appset platform-addons
argocd appset get platform-addons
What’s happening
ApplicationSet is a CRD whose spec contains one or more generators and a template. The controller iterates the generators, substitutes the resulting parameters into the template, and creates one Application per result. The same controller deletes Applications that no longer match (this is the part most people skip the first time — disable goTemplate substitution if you want field-level control, or use Helm parameter overrides under templates).
The shipped generators are:
- List — a literal list of parameters. Simplest, useful for “deploy these named apps”.
- Cluster — iterates clusters registered with Argo CD. Pairs with cluster labels (set via
argocd cluster set --label) so you target subsets (“all prod EKS clusters”). - Git — iterates files or directories in a Git repo. The repo IS the source of truth for what exists.
- SCM Provider — iterates repositories under a GitHub/GitLab org, useful for tenant-per-repo patterns.
- Pull Request — iterates open PRs in a repo, used to spin up ephemeral preview environments.
- Matrix — Cartesian product of two generators (e.g. Cluster × Git, giving every chart on every cluster).
- Merge — combine multiple generators, picking unique keys.
The template body uses Go template syntax in 0.10+, or the older {{ .name }} placeholder syntax. Pick one convention per repo.
The procedure
-
Label your clusters first. Cluster Generator depends on labels:
argocd cluster set https://prod-eu.example.com \ --label env=prod \ --label region=eu-west-1 \ --label cloud=eks argocd cluster set https://prod-us.example.com \ --label env=prod \ --label region=us-east-1 \ --label cloud=eks argocd cluster set https://staging.example.com \ --label env=staging \ --label cloud=eks -
Use the List generator for a static fleet roll. This is the simplest pattern — deploy the platform stack to a known set of clusters:
apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: platform-addons namespace: argocd spec: generators: - list: elements: - cluster: prod-eu url: https://prod-eu.example.com - cluster: prod-us url: https://prod-us.example.com template: metadata: name: '{{cluster}}-cert-manager' spec: project: platform source: repoURL: https://github.com/example/gitops path: addons/cert-manager targetRevision: main destination: server: '{{url}}' namespace: cert-manager syncPolicy: automated: prune: true selfHeal: true -
Switch to Cluster generator when the fleet grows. With cluster labels in place, you let Argo CD enumerate clusters for you:
spec: generators: - clusters: selector: matchLabels: env: prod template: metadata: name: '{{name}}-cert-manager' spec: project: platform source: { repoURL: '...', path: addons/cert-manager, targetRevision: main } destination: server: '{{server}}' namespace: cert-managerNow adding a new prod cluster (
argocd cluster add ... --label env=prod) automatically gets cert-manager deployed — no ApplicationSet edit. -
Use Matrix for “every add-on on every cluster”.
spec: generators: - matrix: generators: - clusters: selector: matchLabels: { env: prod } - git: repoURL: https://github.com/example/gitops revision: main directories: - path: addons/* template: metadata: name: '{{name}}-{{path.basename}}' spec: project: platform source: repoURL: https://github.com/example/gitops path: '{{path}}' targetRevision: main destination: server: '{{server}}' namespace: '{{path.basename}}' syncPolicy: automated: { prune: true, selfHeal: true }Add a new add-on by creating a folder under
addons/. Add a new prod cluster by labeling it. The Cartesian product handles the rest. -
Use Pull Request generator for ephemeral previews. This generator opens an Application per PR in a repo:
spec: generators: - pullRequest: github: owner: example repo: webapp tokenRef: secretName: github-token key: token template: metadata: name: 'preview-{{number}}' spec: source: repoURL: https://github.com/example/webapp path: chart targetRevision: '{{head_sha}}' helm: parameters: - name: image.tag value: '{{head_sha}}' destination: server: https://preview.example.com namespace: 'preview-{{number}}' syncPolicy: automated: { prune: true, selfHeal: true }Close the PR, the Application is deleted, the namespace is pruned. The cluster stays clean.
-
Pin the controller version. ApplicationSet evolves quickly. A minor bump can change template substitution semantics. Pin via the Argo CD chart’s
applicationSet.image.tagand read the changelog before upgrading.
Operational notes
generatorsorder does not matter for output, but it matters for failure surface — a slow Git generator can stall the whole ApplicationSet reconciliation. Move expensive generators last in Matrix when possible.- Template name collisions silently overwrite. Two generators producing the same
{{name}}value leave one Application standing. Add a sufficient discriminator to the template name (path, env, number). - Pruning is opt-in via
syncPolicy.automated.prune. Without it, deleting a generator element leaves the Application but stops syncing. The Application becomes orphaned drift. Always set prune. - The Git generator paths use globs that include directories matching only at the leaf level.
addons/*does NOT recurse intoaddons/foo/sub. Usepathpatterns deliberately. - Pull Request generator requires a token with org-wide read. A repo-scoped token cannot enumerate PRs across organizations. Issue it with the smallest org scope that suffices.
Stack Harbor designs the ApplicationSet topology for clients running multi-cluster Argo CD — cluster label conventions, Matrix patterns for platform add-ons, PR-based preview environments, and the operational guardrails that keep generators from spinning up unbounded apps. See how we run that lifecycle inside managed Kubernetes operations.