Argo CD ApplicationSets for multi-cluster deployments

What Argo CD ApplicationSets do for multi-cluster deployments

ApplicationSets let you define one Application template and have Argo CD generate many Application resources from it, one per cluster, Git directory, pull request or list entry. The bundled ApplicationSet controller runs inside Argo CD and watches ApplicationSet objects. It reads the parameters produced by each generator and renders the template for every combination, so a change to the template reaches every generated Application without someone editing each one by hand. Teams usually reach for this when they run the same workload across many clusters or environments and maintaining one hand-written Application per target has become a source of drift and mistakes. The controller offers four core generators. The *List* generator uses a fixed set of parameters you write into the manifest, which suits a small, stable set of targets. The *Cluster* generator iterates over clusters registered with Argo CD, using their labels and annotations, so new clusters are picked up when they are registered. The *Git* generator creates Applications from directories or JSON files in a repository, which fits a repository layout with one folder per environment or tenant. The *Matrix* generator combines the output of two generators, for example every cluster crossed with every application folder. Single Applications remain the better choice for one workload in one cluster, or for a service whose configuration differs enough that a shared template would hide important choices.

Before you adopt generators, confirm which generator fits your cluster inventory and repository layout, and whether the Cluster generator's labels are consistent enough to act as a selection key. Cluster registration, the RBAC that controls who may create or change ApplicationSets, and the guardrails that limit how far a single template change can roll out are design decisions that shape the rest of the build. Those topics are covered in the sections that follow. For the license and support model, Argo CD is part of the Argo project and is released under the Apache License 2.0 (SPDX: Apache-2.0). The project itself offers no paid edition, so the cost of running ApplicationSets is the engineering time to design, operate and upgrade them, not a license fee. The official project repository, argoproj/argo-cd on GitHub, is the place to check the generator documentation for the release you plan to run.

Choosing between the List, Cluster, Git and Matrix generators

The List generator produces parameters from a fixed list written directly in the ApplicationSet manifest. Each element is a set of key-value pairs, and the template renders one Application per element. Because the list lives in Git, every new target is a reviewed change, which suits a small, stable set of environments that rarely changes, such as a production and a staging cluster owned by one team.

Parameters produced: whatever keys you define per element, such as cluster, url and namespace, with no discovery of live state.
Typical fit: a handful of named environments where each one needs hand-written values.
Main failure mode: the list drifts from reality, so a cluster that was decommissioned keeps its Application or a new cluster is never added.
Illustrative example: an element with env: staging and url pointing at a staging API endpoint, rendering one Application per listed environment.
Maintenance cost: every addition is a manual edit, so ask who owns the list and how changes are reviewed.

Confirm that your environment list is the source of truth and that someone reviews it when clusters change.

The Cluster generator reads the cluster secrets that Argo CD already holds and produces one parameter set per registered cluster. Labels on those cluster secrets can filter which clusters match, and the generated parameters include the cluster name, server URL and any metadata labels you attach. It fits fleets where clusters come and go and should receive the same baseline applications, such as monitoring agents or ingress controllers.

Parameters produced: name, server and label values taken from each registered cluster secret.
Typical fit: a platform baseline pushed to every cluster that carries a matching label.
Main failure mode: a cluster registered without the expected label is silently skipped, or a broad selector reaches clusters that should be excluded.
Illustrative example: a selector matching clusters labeled tier: production, so a new production cluster receives the baseline on registration.
Access consideration: the controller can see every registered cluster, so the ApplicationSet's scope and project boundaries matter.

Check which label keys your cluster registration process sets and confirm that the matching rules are tested against a non-production cluster first.

The Git generator produces parameters from either the directory structure or a JSON or YAML file in a Git repository. Directory mode creates one Application per matching folder, and file mode reads values from config files. Teams that organize deployments as folders per environment or per application use it so that adding a folder adds an Application without touching the ApplicationSet.

Parameters produced: path.basename, path.path and related values from directories, or the keys defined inside each matched file.
Typical fit: one folder per application or per environment, where folder creation is the approval step.
Main failure mode: a stray or half-finished folder is picked up and deployed, or a path pattern matches more directories than intended.
Illustrative example: a glob such as apps/* that creates one Application for each subfolder under apps.
Repository risk: whoever can commit a new folder can cause a new deployment, so pair this with branch protection and review rules.

Confirm the glob patterns against the actual repository layout and decide how the team will handle folders that are not ready to deploy.

The Matrix generator combines the parameters of two child generators and produces their cross product, so each cluster is paired with each application or each environment. It is the usual choice when a set of applications must run on a set of clusters without writing every pair by hand. The risk is that the output grows multiplicatively, so two modest inputs can produce far more Applications than anyone reviewed.

Parameters produced: the merged keys from both child generators for every pairing.
Typical fit: a fixed set of applications rolled out to a set of clusters, where each pair should exist.
Parameter explosion risk: an input of 10 clusters and 20 folders yields up to 200 Applications, so count the pairs before enabling the set.
Key collisions: if both children define the same key name, the values can overwrite each other, so use distinct names.
Illustrative example: a Cluster generator crossed with a Git generator on apps/*, producing one Application per cluster per app folder.

Ask for a dry run or rendered output that lists every generated Application before the first sync, and set a plan for how new clusters or apps are added.

Design decisions that shape the ApplicationSet

An ApplicationSet turns one template into many Applications, so most of its later problems trace back to a few early choices. The cards below cover the decisions a partner works through with your team before any generator is written, and they flag the items to confirm against the Argo CD version you run.

Template scope and blast radius

Decide how much one ApplicationSet controls. A single template that generates Applications for every cluster means one bad change reaches every cluster on the next reconciliation. Scope each ApplicationSet to one application, one team or one environment tier, and keep the template small enough that a reviewer can read the generated Application in full. Confirm the default behavior of the ApplicationSet controller for generated Applications that disappear from the generator output on your installed version.

Parameter naming across generators

Generators such as the Cluster and Git generators emit parameters with fixed key names, and the template depends on those names. Agree on a naming convention for labels, annotations and directory-derived values before writing templates, so that a renamed cluster label or Git directory does not silently produce Applications with empty fields. Test each generator's output with a dry run against the installed version, because the exact parameter keys are version-dependent and should be confirmed in the generator documentation.

One ApplicationSet per application or per cluster

Choose whether an ApplicationSet owns one application across many clusters or many applications across one cluster. The first keeps a product's rollout logic in one place. The second suits platform add-ons that every cluster needs. Mixing both in one ApplicationSet makes ownership and sync behavior hard to explain to auditors and on-call engineers. Ask your team which model matches how cluster access and release approval already work, then document the choice in the repository that holds the ApplicationSets.

Go templates or fasttemplate

ApplicationSets can render templates with the standard Go template engine or with the fasttemplate engine, and the two differ in how they handle missing keys, nested values and conditionals. Pick one per ApplicationSet and state it in the review checklist, since a template written for one engine can render incorrectly in the other. Confirm which template options your installed version exposes and whether the Go template mode is enabled by default there, and test rendering against a sample cluster before the first sync.

Project inheritance for generated Applications

Each generated Application needs a project, and the project decides which repositories, destination clusters and namespaces it may use. Set the project explicitly in the template rather than relying on a default, and confirm that the project names generated from cluster or directory values exist before the sync. Generated Applications that point at a project that does not allow the destination are rejected, which is the desired control. Review project boundaries together with the RBAC that lets teams create or edit the ApplicationSet itself, because an ApplicationSet can create Applications that its author could not create directly.

Rollout guardrails and sync policy

Decide whether generated Applications sync automatically, and whether a change to the ApplicationSet template reaches every cluster at once. Automated sync on generated Applications removes the human checkpoint between clusters, so many teams add a progressive rollout strategy, or keep automated sync off for production clusters. Record the decision per environment and confirm the rollout strategy options and their field names on the installed version, since they have changed across releases.

How a partner sets up ApplicationSets across clusters

The sequence below moves from a confirmed Argo CD version to generated Applications that a team has verified on every destination cluster, with access and guardrails set before the first sync.

Confirm the Argo CD version and install
The partner checks which Argo CD minor version the organization runs and whether it still receives patch releases, using the project's release cadence. The control plane is installed or upgraded in the management cluster, and the ApplicationSet controller is confirmed to be running with the same release as the rest of Argo CD. Done means the version is recorded, the controller pods are healthy, and a trivial test Application syncs successfully. Confirm the supported version set with your own release policy before choosing a target.
Register each destination cluster with least-privilege credentials
Each destination cluster is added to Argo CD using a service account scoped to the namespaces and resource kinds that the planned Applications need, rather than a cluster-admin token. The partner records which cluster labels will drive generator selection, such as environment or region, because the Cluster generator depends on them later. Done means every cluster appears in Argo CD with the expected labels, and a test sync into each cluster is denied for resources outside its allowed scope. Ask your platform team how cluster credentials are rotated and stored.
Define project boundaries for generated Applications
The partner creates one or more Argo CD Projects that limit which source repositories, destination clusters and namespaces generated Applications may use. Source repositories and destinations are listed explicitly so a template cannot point an Application at an unapproved Git location or cluster. Done means a deliberately out-of-scope test Application is rejected by the Project, and the allowed list matches the approved design document.
Design and test generator parameters in a non-production cluster
The partner chooses the generators (List, Cluster, Git or Matrix) that match how clusters and repositories are organized, then writes the template and parameters. Generators are tested first in a non-production cluster, where the team reviews the Applications the controller produces and confirms names, labels, targets and sync policy. Done means the rendered Applications match the design for every test cluster, and a change to a cluster label or Git directory produces the expected addition or removal. Ask the partner to show the dry-run or rendered output before any production cluster is included.
Add RBAC for who can create or change ApplicationSets
The partner defines which groups may create, edit or delete ApplicationSets, and which may only view them, mapping those roles to the organization's identity groups. Because ApplicationSets can create many Applications at once, write access is limited to platform owners and the change process is documented. Done means a user without the role is refused when editing an ApplicationSet, and a user with view access can see the generated Applications without changing them. Confirm group mapping with your identity administrators before the role is granted.
Roll out to production clusters in a controlled order
The partner enables the ApplicationSet for the first production cluster or a small set of clusters, watching the generated Applications for sync errors before widening the target set. Rollout steps are agreed in advance, and any progressive sync feature is confirmed in the installed version before use. Done means every intended cluster has a generated Application that is Synced and Healthy, and the rollback steps have been written down and tested. Confirm the rollout order and approval steps with the change owner.
Verify generated Applications and record the evidence
After rollout, the partner checks that every generated Application points to the approved repository path, targets the intended cluster and namespace, and carries the expected labels and sync settings. Alerts and access checks are confirmed, and the configuration is stored in Git so changes are reviewed. Done means a written verification record lists each generated Application, its source, destination and status, and the team can reproduce the list from the repository alone.

ApplicationSet options and when each one fits

This table compares the ApplicationSet settings that change how generated Applications are created, synced and deleted. Read each row as a decision: the option, when it fits a multi-cluster rollout, and the risk a reviewer should check before enabling it. Most of the risk sits in deletion behavior and in automated sync on generated Applications.

Option	When it fits	Risk to review
goTemplate	Templates need conditionals, loops or functions beyond simple string substitution across many generated fields	Template errors can fail the whole set, so test rendering against every cluster and repository the generator returns
preserveResourcesOnDeletion	Deleting an ApplicationSet should leave the workloads it created running while ownership is reviewed	When left on, removing a generator entry or the set may leave orphaned resources that teams assume were cleaned up
Template syncPolicy (automated, prune, selfHeal)	One policy must apply to every cluster or environment the set produces, with consistent drift handling	Automated prune on a broad generator can delete resources across many clusters from a single Git or label change
templatePatch	A few clusters or environments need a different field from the shared template without a second ApplicationSet	Patches are easy to scatter and hard to audit; confirm which generated Applications receive each patch before syncing
project field in the template	Each generated Application should land in a specific Argo CD project that carries that team's destination and source limits	A wildcard or overly broad project lets generated Applications reach clusters or repositories the owning team should not touch
Generator list versus cluster generator	You want a fixed, reviewed list of targets, or you want every registered cluster matched by labels	Adding a cluster label or registering a new cluster can create Applications automatically, so restrict who can label clusters
Git generator (directories or files)	Each folder or file in a repository maps to one environment or cluster configuration	Creating or renaming a directory can generate or remove Applications; review generator path changes like code changes
Matrix generator combinations	Targets are defined by two dimensions, such as clusters crossed with applications	The number of generated Applications grows multiplicatively; confirm the expected count before enabling the set
RollingSync strategy	Changes must move through clusters in steps rather than all at once	Generated Applications lose automated sync under this strategy, so plan how each step is triggered and verified

How cluster registration and RBAC limit blast radius

One ApplicationSet can reach every cluster it is allowed to generate Applications for, so the blast radius of a multi-cluster deployment is set by three things: which clusters Argo CD holds credentials for, which destinations each project permits, and who may create or edit ApplicationSet resources. A cluster generator reads registered clusters, so a registration that was added for a sandbox or a single team can quietly become a target for every template in the set. Before the first ApplicationSet goes live, list every registered cluster, confirm its credentials are scoped to what Argo CD actually needs, and check that each cluster is meant to receive the templated workloads. Cluster credentials are redacted from API responses and logs, but that protection does not limit what a registered credential can do on its target cluster.

Projects are the main control on where Applications can land. Each project's destinations, source repositories and cluster resource allowances should be written narrowly for each team, and the ApplicationSet's generated Applications should be checked against them during review. Who can edit an ApplicationSet matters as much as the project boundary, because an edit to a shared template changes many Applications at once. Restrict write access to ApplicationSet resources through Argo CD RBAC, and map that access from SSO groups using the mapping described in the Argo CD user management documentation. Since version 3.0, Dex-based RBAC matches on the federated_claims.user_id claim, so confirm that group and user mappings still resolve after any upgrade.

Repository access follows the same logic. Since 3.0, repositories must be defined as Kubernetes Secrets rather than in the argocd-cm ConfigMap, so repository credentials are managed like other cluster objects and must be reviewed as part of the same access model. Confirm which repositories each project can read, because a generator that pulls from a shared Git source can fan out content from that repository to every destination. Disable the built-in admin user with admin.enabled set to false once SSO and local users work, and verify the change in a non-production instance first. Your own team should confirm the exact RBAC and project settings for its Argo CD version against the official documentation before rollout.

Security and operational risks to control

An ApplicationSet can generate many Applications from one template, so a single mistake or a compromised input can reach many clusters at once. The controls below cover what the repo-server executes, what the API accepts, what credentials can expose, and how a generator change spreads.

Untrusted repository content

The repo-server runs Helm and Kustomize on repository content to render manifests. A generator that reads from a repository a team does not control lets that content run inside Argo CD's rendering path. Restrict which repositories the generators and Applications may reference, and review who can merge to those paths before they feed a fleet.

Out-of-tree file access

Helm and Kustomize can reference files outside the source path if a template or overlay points there. Within an ApplicationSet, one Git generator path can therefore pull in content from places the template author did not intend. Confirm the source path boundaries for each generated Application and test a render with a deliberately out-of-tree reference to see whether it resolves.

Credential redaction

Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs. That protects the values in the UI and CLI output, but it does not stop a user with broad read access from reading Secrets in the Argo CD namespace or from generating a list of registered clusters. Check who can read repository and cluster Secrets, and confirm that generator-driven cluster lists are visible only to the platform team.

JWT-only API access

Argo CD authenticates API requests only with JSON Web Tokens. Any automation that calls the API, including pipelines that trigger ApplicationSet refreshes, needs a token with a scoped lifetime and a defined owner. Plan token issuance and rotation as part of the same design as the generator RBAC, and remove tokens that belong to people who have left.

Disabled admin user

The user management guidance recommends using the built-in admin user only for initial setup and disabling it by setting admin.enabled to false once local users or SSO are configured. A live admin login bypasses the project and generator RBAC your team has defined. Record who holds break-glass access, and confirm that sign-in works through SSO before disabling the account.

Generator changes that prune at scale

A change to a generator's list, cluster selector or template can make many generated Applications disappear in one sync. If automated prune is enabled on the ApplicationSet, the controller removes Applications that no longer match, and their resources follow. Review generator diffs as carefully as code, and test the change against a staging selector before it reaches production clusters.

Controller sharding for large fleets

A single application controller can become the bottleneck as the number of clusters and generated Applications grows. The high availability guidance says the controller can be sharded across replicas. Decide the shard layout before the fleet grows, and measure reconciliation lag after each new generator. Confirm the sharding method and replica count against the version you run.

Questions teams ask before running ApplicationSets across clusters

What drives the cost of an ApplicationSet design for multi-cluster deployments?

The main cost driver is how many clusters, repositories and teams the generators must cover, and how many rules the design needs to keep them apart. A design that uses one List generator for a few clusters is small. A design that combines Cluster, Git and Matrix generators across cloud accounts, with per-team projects and rollout guardrails, takes more design time, more testing and more review. Costs are one-time for the design and build, then recurring for maintenance as clusters and templates change. Ask any partner for a quote that lists the generators in scope, the number of clusters and repositories, the RBAC model, the rollout approach and the test environments used to verify each generated Application. Cost is set by the written scope, not by a list price.

How long does a first ApplicationSet design take?

No fixed duration applies, because it depends on the number of clusters, the shape of the repository layout and how many teams share the design. The work usually moves through four stages: deciding which generator fits each use case, registering clusters with the right credentials, defining projects and RBAC, and testing the generated Applications in a non-production cluster. Each stage can expand when the source repositories are inconsistent or when ownership of clusters is unclear. Ask for a timeline in the written scope that names the stages, the review points and the dependencies on access that your team must provide.

What must our team provide before a partner starts ApplicationSet work?

A partner needs enough access and context to model your real deployment, not a sample. Typical inputs include a list of target clusters with their owners and network paths, the Git repositories and folder layouts the templates will read, the team and project boundaries that RBAC must enforce, and the identity groups that map to Argo CD roles. You should also provide a non-production cluster where generated Applications can be tested safely, and a named approver for generator and template changes. Confirm with your partner which credentials they will need and how those are issued, rotated and removed.

Can an internal platform team build ApplicationSets without outside help?

Yes, a platform team with Kubernetes and Argo CD experience can build ApplicationSets alone, especially for a small number of clusters and one owning team. The harder parts are generator design choices that affect blast radius, cluster registration that does not leak long-lived credentials, and RBAC that keeps one team from changing another team's Applications. Teams without a dedicated reviewer often find that templates grow without a clear model. A useful internal check is whether two engineers can explain, from the repository alone, which clusters a change will reach and what sync policy it will carry.

When is a partner worth bringing in for multi-cluster Argo CD?

A partner is most useful when the design has to cross several ownership lines at once, such as separate cloud accounts, regulated environments, several business units and a change process that auditors will review. It is also useful when the current install has grown by accident and needs restructuring before new clusters are added. Ask whether the partner will leave behind documentation, test cases and a runbook your team can operate, and whether the engagement is fixed-scope or a retainer for ongoing change. DeployOpen plans and implements these designs inside your own infrastructure, and prepares evidence for compliance assessments without issuing audit reports.

How do Argo CD upgrades affect applications generated by an ApplicationSet?

Upgrades can change how generated Applications behave, so each upgrade needs a test against your templates before production. The 2.14 to 3.0 upgrade notes state that update and delete RBAC now apply only to the application itself, that logs access needs an explicit logs, get permission, and that annotation-based resource tracking is the default. Those changes affect which teams can modify generated Applications and how resources are tracked. Argo CD also supports only the three most recent minor versions with patch releases, so plan a recurring upgrade cadence. Ask your partner for an upgrade test plan that replays each generator against the target version in a staging cluster.

What should we check in an ApplicationSet before it reaches production clusters?

Check which clusters each generator selects, what the template renders for each one, and which sync policy the generated Applications inherit. Confirm that the generated Applications belong to the correct project, that the destination namespaces and server addresses are correct, and that repository credentials are defined as Kubernetes Secrets, as Argo CD 3.0 requires. Also review how the Helm or Kustomize steps read repository content, since the security documentation notes that the repo-server runs them on that content and that untrusted repositories are a risk. A dry run in a non-production cluster will show most mistakes before a change reaches live clusters.

How DeployOpen scopes and supports ApplicationSet rollouts

Every ApplicationSet engagement starts with a written scope that names the generators in use, the clusters and repositories they template across, the RBAC and rollout guardrails to be built, and the deliverables the client receives. DeployOpen agrees that scope and its timeline before work begins, so the client knows which generator decisions are settled and which need sign-off. Because Argo CD runs inside the client's own clusters and cloud accounts, the controller, its Projects, the registered cluster credentials and the Git repositories stay under the client's control from the first day. Confirm in the quote who owns each cluster registration and who approves changes to the generator templates.

Testing focuses on what the generators produce, not only on whether Argo CD starts. Before go-live, the generated Application manifests are reviewed against the intended cluster, namespace and source for each target, and edge cases such as a cluster label removed or a Git directory renamed are exercised in a non-production environment. Each ApplicationSet's syncPolicy settings, its goTemplate options and any RollingSync steps are documented alongside the test results so the client's team can rerun them after a change. Handover includes runbooks for adding a cluster, retiring one and rolling back a template change.

Ongoing support, upgrades and continuous testing are available as retainers, which suit teams that add clusters or Argo CD minor releases regularly. Argo CD publishes minor releases four times a year and patches only its three most recent minor versions, so a retainer can cover checking each upgrade against generator behavior before it reaches production. Ask any partner, including DeployOpen, which upgrade and test activities are included in the retainer and which are billed separately, and how quickly they respond to a failed sync caused by a template change.