ArgoCD ApplicationSets for Many Clusters

By Kokil Thapa | Last reviewed: September 2026

Managing ten Kubernetes clusters with hand-written Argo CD Applications does not scale. Each new region or tenant means another YAML file, another review, and another place for drift. ArgoCD ApplicationSets for many clusters solve that by generating Applications from one template and a generator list. If you already run Argo CD GitOps on Kubernetes, ApplicationSets are the next step when one control plane must reach prod, staging, DR, and edge nodes without copy-paste.

What Are ArgoCD ApplicationSets and Why Do You Need Them for Many Clusters?

An ApplicationSet is a Kubernetes custom resource. It sits beside the Application CRD that Argo CD already uses. The ApplicationSet controller reads generator output and renders an Application for each item.

Without ApplicationSets, a platform team maintains separate Application manifests per cluster. That works for two clusters. At eight clusters, mistakes multiply. Someone forgets to add staging-eu. A sync policy change lands in prod but not DR.

ApplicationSets encode the rule once: “for every registered cluster matching label env=production, create an Application pointing at overlays/{{name}}.” Add a cluster to Argo CD, label it, and the controller creates the Application automatically.

This pattern fits teams shipping the same microservice or platform add-on everywhere. It also fits multi-cluster GitOps patterns where one management cluster runs Argo CD and remote clusters hold workloads only.

Which ApplicationSet Generators Work Best for Multi-Cluster Deployments?

Generators produce parameter sets. The template substitutes values like {{name}} and {{server}}. Pick the generator that matches how your cluster inventory is stored.

Cluster generator

The cluster generator reads clusters registered in Argo CD. Filter by labels or names. This is the default choice for ArgoCD ApplicationSets for many clusters when Argo CD already holds cluster secrets.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: platform-addons
  namespace: argocd
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            argocd.argoproj.io/secret-type: cluster
            environment: production
  template:
    metadata:
      name: 'addons-{{name}}'
    spec:
      project: platform
      source:
        repoURL: https://github.com/org/gitops-platform.git
        targetRevision: main
        path: 'clusters/{{name}}/addons'
      destination:
        server: '{{server}}'
        namespace: argocd
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Register each remote cluster with argocd cluster add or a ClusterSecret. Label secrets consistently. The generator only sees what Argo CD knows.

Git generator

The Git generator scans a repository directory tree. Each folder becomes one Application. Pair it with a cluster generator via matrix when folder names map to cluster names.

generators:
  - matrix:
      generators:
        - git:
            repoURL: https://github.com/org/gitops-apps.git
            revision: main
            directories:
              - path: apps/payment-service/overlays/*
        - clusters:
            selector:
              matchLabels:
                tenant: shared

Matrix multiplies generators. A Git folder list times a cluster list yields many Applications. Watch cardinality: ten overlays times twelve clusters is 120 Applications from one ApplicationSet.

List and pull-request generators

The list generator suits fixed, small inventories—three DR sites you rarely change. The pull-request generator creates preview Apps per PR. That helps app teams, not fleet-wide platform rolls.

Official docs describe all generators in the ApplicationSet Generators reference. Read that page before mixing matrix and merge generators.

How Do You Install and Configure ApplicationSets on an Argo CD Control Plane?

ApplicationSets ship as a separate controller. Modern Argo CD installs include it, but verify the CRD exists before you apply manifests.

1. Install or upgrade Argo CD on your management cluster. Follow the same baseline as setting up GitOps with Argo CD.
2. Confirm the ApplicationSet CRD: kubectl get crd applicationsets.argoproj.io.
3. Enable the ApplicationSet controller if your Helm values disabled it.
4. Register remote clusters with consistent labels on cluster secrets.
5. Apply ApplicationSet manifests through an App-of-Apps or a dedicated bootstrap Application.
6. Verify generated Applications in the Argo CD UI or with kubectl get applications -n argocd.

On Ubuntu management nodes I maintain for clients, the pattern mirrors other Git-based deploy pipelines. Git holds truth. The cluster reconciles state. The difference is Kubernetes-native scope instead of symlink releases on a single VM.

Store ApplicationSet YAML in the same GitOps repo as cluster overlays. Never apply them only from a laptop. That breaks audit and rollback.

AppProject boundaries

Each generated Application references an AppProject. Restrict destinations and repos per project. Platform addons belong in a platform project. Tenant apps belong in tenant-scoped projects.

Pair AppProjects with Kubernetes RBAC hardening on each spoke cluster. Argo CD's cluster credential is powerful. Limit namespace scope where possible.

What Sync Policies and Rollout Patterns Should You Use Across Many Clusters?

Automated sync with prune works for homogenous fleets. It is risky when clusters differ in capacity, timezone, or compliance rules. Stagger rolls instead of syncing every cluster at once.

Sync waves and progressive delivery

Use sync waves in overlay manifests so dependencies install in order. Platform CRDs wave 0, operators wave 1, apps wave 2. Sync waves and hooks in Argo CD apply to generated Applications the same way they apply to hand-written ones.

For progressive multi-cluster rollout, split ApplicationSets by environment or region. Ship staging ApplicationSet first. Promote Git revision only after health checks pass. Some teams use separate branches; trunk-based with tagged revisions is simpler long term.

Ignore differences and drift

Clusters rarely stay identical. Node counts, storage classes, and ingress hosts differ. Use Kustomize overlays per cluster folder. Use ignoreDifferences on fields clusters must mutate locally—replica counts if HPA owns them, for example.

spec:
  template:
    spec:
      ignoreDifferences:
        - group: apps
          kind: Deployment
          jsonPointers:
            - /spec/replicas

Validate generated manifests with a local render step or CI job. A JSON formatter helps inspect rendered Helm output before it hits prod clusters.

What Production Gotchas Break ApplicationSets Across Many Clusters?

ApplicationSets look clean in a demo. Production surfaces edge cases fast. These failures show up repeatedly on real platforms.

Cluster secret hygiene

The cluster generator only matches registered clusters. A typo in label selectors silently yields zero Applications. Document required labels in your platform README. Automate cluster registration in Terraform or Crossplane.

Naming collisions

Application names must be unique cluster-wide in Argo CD. Use a prefix: {{name}}-payment, not bare payment. Matrix generators amplify collision risk.

Resource limits on the management cluster

Five hundred generated Applications stress the Argo CD API server and UI. Split by domain or use ApplicationSet syncPolicy preservation options. Monitor etcd on the management cluster—the same concerns that apply to etcd in Kubernetes apply to Argo CD's backing store.

Secrets and multi-tenant repos

Do not embed secrets in generator templates. Use External Secrets Operator or Sealed Secrets per spoke cluster. Keep Git paths tenant-scoped when one repo serves many teams.

RBAC and blast radius

One bad ApplicationSet can push broken manifests to every production cluster in minutes. Require PR review on ApplicationSet paths. Use CODEOWNERS. Restrict who can label cluster secrets as production.

In my experience working on production deployment pipelines, the failure mode is rarely the controller itself. It is inconsistent cluster metadata and skipped staging validation.

How Does an ApplicationSet Fleet Fit Into a Broader GitOps Architecture?

ApplicationSets solve Application sprawl. They do not replace good repo layout or cluster onboarding docs. A typical layout:

• bootstrap/ — App-of-Apps that installs ApplicationSets and core projects
• applicationsets/ — platform-wide generators
• clusters/<name>/ — Kustomize overlays per spoke
• apps/<service>/base plus overlays/<cluster> — tenant workloads

This mirrors patterns in GitOps across multiple clouds with Argo CD and complements multi-cluster Kubernetes across clouds. Some teams run Rancher for cluster lifecycle and Argo CD for workload GitOps. The split is fine if roles are clear.

For Laravel or custom app teams, Kubernetes may host only queues and workers. The same ApplicationSet pattern deploys Redis, Horizon, and ingress controllers to every spoke. Application code still ships through your existing CI. GitOps owns cluster state, not necessarily every PHP release.

Compare tooling choices in Flux CD vs Argo CD compared if you have not standardised yet. Flux has its own templating story. Argo CD ApplicationSets fit teams that already invested in the Argo UI and RBAC model.

Enterprise platforms with mixed compliance needs often split ApplicationSets by region. EU clusters never share a generator with APAC prod. The duplication is intentional blast-radius control.

Ongoing fleet work belongs with platform ops. If you need help designing GitOps repos or Linux system administration for management clusters, treat it as infrastructure product work—not a one-off YAML dump.

Reference implementations and upstream behaviour are documented in the Argo CD ApplicationSet operator manual. Cross-check generator fields there before upgrades. The Kubernetes project overview at kubernetes.io helps onboard developers new to CRDs and controllers.

Onboarding a new spoke cluster should be a checklist: register cluster, apply labels, confirm overlay folder exists, watch Application appear, run smoke test. Document it beside your declarative Kubernetes deployment runbooks.

Teams running booking or multi-region apps—like platforms I've seen on travel and legal-tech projects—benefit when staging mirrors prod topology. Two clusters in ApplicationSet staging catch overlay bugs before they hit eight prod regions.

Validate ApplicationSet changes in CI with argocd appset generate or plugin-based render tools. Block merge when rendered manifests fail kubeconform or policy checks. Policy-as-code (Kyverno, OPA Gatekeeper) on each spoke catches drift ApplicationSets cannot see.

Storage and backup differ per cloud. Overlays should pin storage classes and ingress annotations per cluster. Do not assume one Helm values file works on EKS, GKE, and on-prem k3s edge clusters without patches.

Cost control matters for Nepal and global SMB clients alike. Right-size management clusters. Argo CD HA mode plus hundreds of Applications runs fine on modest nodes if you prune old revisions and limit repo polling frequency.

When something fails, use Application-level sync history first. Then check ApplicationSet controller logs. Generator misconfiguration often shows as zero children rather than a sync error.

Link ApplicationSets to your wider enterprise application development roadmap when Kubernetes becomes the default deploy target for new services.

Portfolio platforms such as Adventure Third Pole Trek run on traditional Laravel deploy paths today. Hybrid setups—VM or shared hosting for web, Kubernetes for workers—still benefit from ApplicationSets on the cluster side only.

For maintenance contracts, include ApplicationSet and cluster registration steps in handover docs. Future staff should add a region without Slack calls to the original builder. That is the real ROI.

Explore related reading on GitOps Flux vs Argo CD, Rancher for multiple clusters, and active-active vs active-passive multi-cloud when planning HA.

Support and maintenance retainers should cover Argo CD upgrades. ApplicationSet CRD schema changes between Argo CD versions can require manifest updates.

Custom software development teams new to GitOps should start with one ApplicationSet and three clusters, not matrix generators on day one.

Use regex tester when debugging ApplicationSet label selectors. A wrong regex returns empty generator output with no error banner.

Read about my background if you want a engineer who ships both application code and the pipelines that deploy it.

Key Takeaways

• ArgoCD ApplicationSets for many clusters replace hand-maintained Application lists with one template and a generator.
• Start with the cluster generator when Argo CD already registers your spoke clusters with consistent labels.
• Use matrix generators only when you understand total Application count and UI impact.
• Roll staging ApplicationSets first; promote Git revisions to prod only after health checks pass.
• Guard naming, RBAC, and cluster secret labels—silent empty generators are the most common production surprise.
• Keep ApplicationSet YAML in Git, review it like application code, and validate renders in CI before merge.

People Also Ask

What is the difference between an Argo CD Application and an ApplicationSet?

An Application deploys one source path to one destination cluster. An ApplicationSet is a factory that creates many Applications from a template. You edit the ApplicationSet once; the controller keeps child Applications in sync with generator output.

Can ApplicationSets deploy to clusters outside the management cluster?

Yes. Register external clusters as Argo CD cluster secrets. The template's destination.server field uses each cluster's API server URL. Argo CD agents or credentials must reach those endpoints securely.

Do ApplicationSets work with Helm and Kustomize?

Yes. The generated Application spec supports the same source types as a normal Application—Helm charts, Kustomize paths, Jsonnet, or plain directories. Overlays per cluster remain the usual pattern.

How many clusters can one ApplicationSet manage?

There is no hard limit in the CRD. Practical limits depend on Argo CD scale, etcd size, and operator patience in the UI. Dozens to low hundreds of clusters are common; split ApplicationSets by domain if sync latency grows.

Scale GitOps Across Your Cluster Fleet

ArgoCD ApplicationSets for many clusters turn fleet deployment from copy-paste into declarative rules. One template, well-chosen generators, and strict cluster labels beat a folder of nearly identical YAML files every time. Start small, validate in staging, then expand the generator scope as your platform matures.

Need help designing a multi-cluster GitOps repo, hardening your management cluster, or bridging Laravel apps with Kubernetes workers? Contact us to plan a rollout that fits your team size and budget.