Argo CD ApplicationSet: When to Use It and How to Validate Generated Applications

The decision: one manifest per app, or one ApplicationSet?

Platform teams often begin by writing one Argo CD Application manifest for every microservice. When the catalog grows to a few dozen services across development, staging, and production, that becomes dozens of nearly identical YAML files. Changing a sync policy, target namespace, or Helm release name means editing every file by hand. The useful takeaway: if your applications share a template and differ only by a small set of values, replace the repetition with an Argo CD ApplicationSet. If each application is genuinely unique, keep individual manifests.

Constraints to check first

• Argo CD version 2.0 or later; the ApplicationSet controller and CRD did not exist before v2.0.
• The argocd-applicationset-controller deployment is running in the Argo CD namespace.
• You can read from the source the generator will inspect, such as a Git repository or the Kubernetes cluster API.

Supported generator options

Generator	Expands from	Typical use case
List	Explicit names and values you supply	A fixed, known set of applications
Cluster	Clusters discovered by Argo CD	One application per managed cluster
Git	Directories or files in a Git repository	One application per service folder
Merge	Two or more generators combined	Team and environment combinations
Matrix	Cross-product of generator values	Environment × team × region rollouts

Trade-offs

ApplicationSet reduces duplication and lets you update one template instead of many manifests. The cost is a steeper learning curve and a larger blast radius: a mistake in the generator can create dozens of conflicting Applications at once. Individual manifests give you fine-grained control per app but scale poorly as the catalog grows.

Example: generate one Application per service directory

This representative ApplicationSet uses the Git generator to create one Application for each subdirectory under services/ in a configuration repository. Template field names vary by generator and Argo CD version, so review the rendered Applications before relying on them.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: service-catalog
  namespace: argocd
spec:
  generators:
  - git:
      repoURL: https://github.com/example/infrastructure.git
      revision: main
      directories:
        - path: services/*
  template:
    metadata:
      name: "{{path.basename}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/example/infrastructure.git
        targetRevision: main
        path: "{{path}}"
      destination:
        server: https://kubernetes.default.svc
        namespace: "{{path.basename}}"
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Where to run and required permissions

Run kubectl and argocd commands from a workstation with kubeconfig access to the Argo CD cluster, or from a CI runner with the same context. You need read/write permission on the argocd namespace and authentication to the Argo CD API server. Placeholders such as service-catalog and https://github.com/example/infrastructure.git must be replaced with your own values.

Apply and validate

1. Apply the manifest:

kubectl apply -f service-catalog-applicationset.yaml -n argocd

1. Confirm the controller is running and picks up the new resource:

kubectl rollout status -n argocd deployment/argocd-applicationset-controller

1. List the Applications generated by this set:

argocd app list --selector argocd.argoproj.io/application-set=service-catalog

1. Check the controller log for generator or template errors:

kubectl logs -n argocd deployment/argocd-applicationset-controller --tail=50

Expected checks: the number of listed Applications matches the number of directories matched by the generator, each destination namespace matches the directory name, and each Application eventually shows Synced and Healthy.

Diagnostic decision

If the list returns more Applications than expected, the generator pattern is too broad. Narrow the path value or add a git files filter before enabling automated sync. If the list returns nothing, confirm the controller can reach the repository and that the revision exists.

Rollback

Because applying an ApplicationSet creates Application objects, rollback removes the set and its generated Applications unless the retention policy is set to keep them:

kubectl delete applicationset service-catalog -n argocd

Verify removal with:

argocd app list --selector argocd.argoproj.io/application-set=service-catalog

Limitations

• ApplicationSet does not replace per-app customization that cannot be expressed through template variables.
• Generated Applications share the same project and source structure by default; complex overrides require generator-specific fields.
• The feature is unavailable on Argo CD versions earlier than 2.0.

Practical way to check the result

After the controller reconciles—typically within seconds—run:

argocd app list --selector argocd.argoproj.io/application-set=service-catalog --output wide

Confirm the expected count, destination server, and namespace for each row. Then inspect one generated Application:

argocd app get <generated-app-name>

If the Application is not Synced, check the application controller logs and the target cluster for missing RBAC or namespace resources.