GitOps made simple: Using Argo CD ApplicationSet to deploy apps across clusters

Deploying a single application to one Kubernetes cluster is straightforward. The friction appears when you need to deploy many apps to many clusters, or keep a monorepo of application definitions synchronized across environments. Argo CD’s ApplicationSet controller simplifies that problem by turning a single declarative resource into many Argo CD Application objects, using templating and data-driven “generators” to automate the work. This article explains what ApplicationSet does, how its main generators work, and shows a compact example (Git + Cluster via a Matrix generator) so you can see the pattern in a single glance.

What problem ApplicationSet solves

• Scaling: instead of authoring dozens or hundreds of Application CRs by hand, you describe a single ApplicationSet and let the controller generate the corresponding Application resources.
• Multi-cluster and multi-app workflows: it maps repository structure, cluster lists, or external SCM metadata into Argo CD Applications that target specific clusters and namespaces.
• Monorepo friendliness: when teams keep many app manifests in a single repo, ApplicationSet can generate one Argo CD Application per folder or per file entry instead of copying templates manually. (argo-cd.readthedocs.io)

What an ApplicationSet is (conceptually)

• A Kubernetes CustomResource (kind: ApplicationSet) that describes:
  • one or more generators (sources of parameters), and
  • an Application template where those parameters are substituted to create individual Argo CD Application resources.
• The ApplicationSet controller watches the CR, evaluates generators, renders the template repeatedly using the generated parameter sets, and creates/updates/deletes Application CRs accordingly. The controller itself only manages Application CRs — it does not apply app manifests to clusters (that remains Argo CD’s job). (argocd-applicationset.readthedocs.io)

Generators: the data sources that drive creation Generators produce parameter dictionaries that feed into the Application template. Common generator types include:

• List: a literal list of key/value elements you provide directly in the ApplicationSet. Useful for small fixed sets. (argo-cd.readthedocs.io)
• Cluster: enumerates clusters that Argo CD knows about by reading cluster secrets in the argocd namespace. It exposes fields like name, server, and labels for templating. This is how you target many clusters automatically. (argo-cd.readthedocs.io)
• Git: inspects a repository — directory structure or JSON/YAML files — and emits parameters for each found item (great for monorepos). (argo-cd.readthedocs.io)
• Matrix: composes two generators and produces the Cartesian product of their outputs. For example, pair every discovered app in Git with every selected cluster and generate an Application for each combination. (argo-cd.readthedocs.io)

There are also SCM-provider, pull-request, merge, plugin, and cluster-decision-resource generators for advanced automation and integrations. The generator model is the key idea: separate parameter discovery from template rendering so a single declarative spec can produce many Applications. (argo-cd.readthedocs.io)

A compact example: Git directory + Cluster with Matrix Below is a minimal, focused ApplicationSet that demonstrates the common pattern: discover application folders in Git, enumerate clusters known to Argo CD, and generate an Application per (app, cluster) pair.

apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: apps-to-clusters namespace: argocd spec: goTemplate: true generators:

• matrix: generators:
  • git: repoURL: https://github.com/example-org/apps-repo.git directory: recurse: true path: apps/*
  • clusters: {} template: metadata: name: ‘-‘ spec: project: default source: repoURL: https://github.com/example-org/apps-repo.git targetRevision: HEAD path: ‘’ destination: server: ‘’ namespace: ‘’

Key notes about the snippet (what the template fields mean)

• The Git generator scans repository folders under apps/* and produces a parameter like path = apps/foo and path.basename = foo.
• The Cluster generator produces cluster-level parameters: name, server, and nameNormalized (cluster names made Kubernetes-safe). Those fields are then substituted in the template (for destination.server and the generated Application name). (argo-cd.readthedocs.io)
• Matrix combines the two generators so you end up with one Application per (app-path, cluster) pair — exactly what you need when the same app should be deployed to many clusters. (argo-cd.readthedocs.io)

How ApplicationSet interacts with Argo CD (what it does and doesn’t do)

• The ApplicationSet controller is installed alongside Argo CD and its sole responsibility is to maintain Application CRs in the Argo CD namespace based on the ApplicationSet spec.
• It does not talk to remote clusters, create non-Application Kubernetes objects directly, or apply manifests; Argo CD itself will reconcile the Application CRs and perform the actual deployments. That separation keeps the ApplicationSet focused on declaration/automation while Argo CD remains the runtime engine. (argocd-applicationset.readthedocs.io)

Practical considerations and cautions

• Clusters must be registered with Argo CD ahead of time: the Cluster generator reads cluster entries (stored as secrets) that Argo CD manages — the generator won’t magically create cluster credentials. (argo-cd.readthedocs.io)
• Templating care: because ApplicationSet uses templating, invalid substitutions can yield invalid names or manifests. For cluster names with disallowed chars, prefer nameNormalized which is safe for Kubernetes resource names. (argo-cd.readthedocs.io)
• Security surface: ApplicationSet can be used to give non-admins a way to generate Applications. That’s powerful but requires careful RBAC and project configuration to avoid permitting deployments to arbitrary clusters or namespaces. The docs call out security implications and recommend caution when allowing broad ApplicationSet usage. (argo-cd.readthedocs.io)
• Resource explosion: Cartesian products (e.g., Matrix across many apps and many clusters) will produce many Applications. Keep an eye on scale and the number of generated objects so the control plane and Argo CD UI stay manageable. (argo-cd.readthedocs.io)

Observability and troubleshooting (concise)

• Generated Applications appear in the Argo CD UI and API like any other Application. Use Argo CD’s UI or the argocd CLI to inspect each generated Application’s sync and health status.
• The ApplicationSet controller logs and the ApplicationSet CR’s status block indicate how many Applications were generated and whether rendering errors occurred. If templating fails, the status on the ApplicationSet resource typically contains helpful messages. (argo-cd.readthedocs.io)

When ApplicationSet makes sense (summary of fit)

• When you manage multiple clusters and need consistent deployment behavior across them.
• When you store many apps in a monorepo and want Argo CD Applications created automatically for each app folder or file.
• When you want to automate per-repo or per-PR behavior (using SCM/Pull Request generators) so Argo CD mirrors higher-level SCM organization without manually crafting many Application objects. (argo-cd.readthedocs.io)

Final note (short) ApplicationSet is a natural extension to Argo CD’s GitOps model: it removes repetitive Application definition work and maps parameter sources (Git, clusters, SCM) into Argo CD Applications using a declarative, templated approach. Understanding the available generators (List, Cluster, Git, Matrix, etc.) and how the controller integrates with Argo CD clarifies when and why to adopt ApplicationSet for multi-app, multi-cluster deployment scenarios. (argo-cd.readthedocs.io)

References

• ApplicationSet introduction and integration with Argo CD (bundled since v2.3). (argo-cd.readthedocs.io)
• ApplicationSet generators overview (List, Cluster, Git, Matrix, Merge, SCM, etc.). (argo-cd.readthedocs.io)
• Cluster generator details (parameters such as name, server, nameNormalized; cluster secrets). (argo-cd.readthedocs.io)
• Matrix generator explanation and examples (how it composes generators). (argo-cd.readthedocs.io)
• Git generator (file and directory modes for monorepo patterns). (argo-cd.readthedocs.io)