Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Use ApplicationSets

ApplicationSets generate multiple Applications from templates, enabling you to deploy the same application across multiple clusters, environments, or namespaces with a single resource definition.

Prerequisites

How ApplicationSets work

ApplicationSets use generators to produce parameters, then apply those parameters to an Application template. Each set of generated parameters creates one Application.

Common generators for EKS deployments:

For complete generator reference, see ApplicationSet Documentation.

Create an ApplicationSet in an additional namespace

You can create ApplicationSets outside the primary Argo CD namespace. Keep the AppProject in the primary Argo CD namespace. Before you create an ApplicationSet in an additional namespace:

For instructions on configuring resource namespaces, see Configure namespaces for Applications and ApplicationSets. For instructions on configuring AppProject source namespaces, see Working with Argo CD Projects.

An ApplicationSet creates its Applications in the same namespace as the ApplicationSet. If you enable only applicationsetcontroller.namespaces, the application controller doesn’t manage the generated Applications.

The following example shows an ApplicationSet that you create in team-a-gitops. The generated Applications are also created in team-a-gitops and use the team-a project:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook-environments
  namespace: team-a-gitops
spec:
  generators:
  - list:
      elements:
      - environment: dev
      - environment: prod
  template:
    metadata:
      name: 'guestbook-{{environment}}'
    spec:
      project: team-a
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps
        targetRevision: HEAD
        path: guestbook
      destination:
        name: in-cluster
        namespace: 'guestbook-{{environment}}'

Apply and view the ApplicationSet and its generated Applications in the source namespace:

kubectl apply -f applicationset.yaml
kubectl get applicationset guestbook-environments -n team-a-gitops
kubectl get applications -n team-a-gitops \
  -l argocd.argoproj.io/application-set-name=guestbook-environments

When you use the Argo CD CLI, identify an ApplicationSet in an additional namespace as <namespace>/<applicationset-name>. For example, use argocd appset get team-a-gitops/guestbook-environments.

List generator

Deploy to multiple clusters with explicit configuration:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook-all-clusters
  namespace: argocd
spec:
  generators:
  - list:
      elements:
      - environment: dev
        replicas: "2"
      - environment: staging
        replicas: "3"
      - environment: prod
        replicas: "5"
  template:
    metadata:
      name: 'guestbook-{{environment}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/guestbook
        targetRevision: HEAD
        path: 'overlays/{{environment}}'
      destination:
        name: '{{environment}}-cluster'
        namespace: guestbook
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

This creates three Applications: guestbook-dev, guestbook-staging, and guestbook-prod.

Cluster generator

Deploy to all registered clusters automatically:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-addons
  namespace: argocd
spec:
  generators:
  - clusters: {}
  template:
    metadata:
      name: '{{name}}-addons'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/cluster-addons
        targetRevision: HEAD
        path: addons
      destination:
        server: '{{server}}'
        namespace: kube-system
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

This automatically creates an Application for each registered cluster.

Filter clusters:

Use matchLabels to include specific clusters, or matchExpressions to exclude clusters:

spec:
  generators:
  - clusters:
      selector:
        matchLabels:
          environment: production
        matchExpressions:
        - key: skip-appset
          operator: DoesNotExist

Git generators

Git generators create Applications based on repository structure:

Example: Microservices deployment

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: microservices
  namespace: argocd
spec:
  generators:
  - git:
      repoURL: https://github.com/example/microservices
      revision: HEAD
      directories:
      - path: services/*
  template:
    metadata:
      name: '{{path.basename}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/microservices
        targetRevision: HEAD
        path: '{{path}}'
      destination:
        name: my-cluster
        namespace: '{{path.basename}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
        - CreateNamespace=true

For details on Git generators and file-based configuration, see Git Generator in the Argo CD documentation.

Refresh Git generators with a webhook

By default, the ApplicationSet controller re-reads the repository on an interval, so new directories or parameter files can take minutes to produce Applications. To have a push refresh the generator immediately, add a webhook in your Git provider that points at ${serverUrl}/api/applicationset/webhook.

This path is specific to the capability, and it is separate from the /api/webhook path that refreshes Applications. If a repository feeds both an ApplicationSet generator and an Application, add a webhook for each path.

For more information about the endpoints and the shared secret, see Webhook configuration for faster sync.

Matrix generator

Combine multiple generators to deploy across multiple dimensions (environments × clusters):

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: multi-env-multi-cluster
  namespace: argocd
spec:
  generators:
  - matrix:
      generators:
      - list:
          elements:
          - environment: dev
          - environment: staging
          - environment: prod
      - clusters:
          selector:
            matchLabels:
              region: us-west-2
  template:
    metadata:
      name: 'app-{{environment}}-{{name}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/app
        targetRevision: HEAD
        path: 'overlays/{{environment}}'
      destination:
        name: '{{name}}'
        namespace: 'app-{{environment}}'

For details on combining generators, see Matrix Generator in the Argo CD documentation.

Multi-region deployment

Deploy to clusters across multiple regions:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: global-app
  namespace: argocd
spec:
  generators:
  - list:
      elements:
      - clusterName: prod-us-west
        region: us-west-2
      - clusterName: prod-us-east
        region: us-east-1
      - clusterName: prod-eu-west
        region: eu-west-1
  template:
    metadata:
      name: 'app-{{region}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/app
        targetRevision: HEAD
        path: kubernetes
        helm:
          parameters:
          - name: region
            value: '{{region}}'
      destination:
        name: '{{clusterName}}'
        namespace: app
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Manage ApplicationSets

View ApplicationSets and generated Applications:

kubectl get applicationsets -n argocd
kubectl get applications -n argocd -l argocd.argoproj.io/application-set-name=<applicationset-name>

Update an ApplicationSet:

Modify the ApplicationSet spec and reapply. Argo CD automatically updates all generated Applications:

kubectl apply -f applicationset.yaml

Delete an ApplicationSet:

kubectl delete applicationset <name> -n argocd

Additional resources