Skip to content

Argo CD ApplicationSet generators for multi-cluster GitOps

Use Argo CD ApplicationSet generators (List, Cluster, Git, Matrix) to template Applications across clusters, environments, and tenants without manifest sprawl.

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

  1. 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
  2. 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
  3. 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-manager

    Now adding a new prod cluster (argocd cluster add ... --label env=prod) automatically gets cert-manager deployed — no ApplicationSet edit.

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

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

  6. Pin the controller version. ApplicationSet evolves quickly. A minor bump can change template substitution semantics. Pin via the Argo CD chart’s applicationSet.image.tag and read the changelog before upgrading.

Operational notes

  • generators order 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 into addons/foo/sub. Use path patterns 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.