ApplicationSet Generators

Different generator types for automating Application creation in Argo CD

Overview

Generators are responsible for generating parameters, which are then rendered into the template: fields of the ApplicationSet resource. Each generator type uses a different data source to produce these parameters.

If you are new to generators, begin with the List and Cluster generators. For more advanced use cases, explore the remaining generators.

List Generator

The List generator generates parameters based on an arbitrary list of key/value pairs. This is the simplest generator type.

Basic Example

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - list:
      elements:
      - cluster: engineering-dev
        url: https://kubernetes.default.svc
      - cluster: engineering-prod
        url: https://kubernetes.default.svc
  template:
    metadata:
      name: '{{.cluster}}-guestbook'
    spec:
      project: "my-project"
      source:
        repoURL: https://github.com/argoproj/argo-cd.git
        targetRevision: HEAD
        path: applicationset/examples/list-generator/guestbook/{{.cluster}}
      destination:
        server: '{{.url}}'
        namespace: guestbook

Clusters must be predefined in Argo CD. The ApplicationSet controller does not create clusters within Argo CD.

Flexible Key/Value Pairs

As of ApplicationSet v0.2.0, any key/value element pair is supported:

spec:
  generators:
  - list:
      elements:
      - staging: "true"
        gitRepo: https://kubernetes.default.svc
      - production: "true"
        gitRepo: https://example.com

Dynamic Elements with elementsYaml

You can dynamically generate list elements from Git by combining with a Matrix generator:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: elements-yaml
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - matrix:
      generators:
      - git:
          repoURL: https://github.com/argoproj/argo-cd.git
          revision: HEAD
          files:
          - path: applicationset/examples/list-generator/list-elementsYaml-example.yaml
      - list:
          elementsYaml: "{{ .key.components | toJson }}"
  template:
    metadata:
      name: '{{.name}}'
    spec:
      project: default
      sources:
      - chart: '{{.chart}}'
        repoURL: '{{.repoUrl}}'
        targetRevision: '{{.version}}'
        helm:
          releaseName: '{{.releaseName}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{.namespace}}'

Cluster Generator

The Cluster generator automatically identifies clusters defined in Argo CD and extracts cluster data as parameters.

How It Works

In Argo CD, managed clusters are stored as Secrets in the Argo CD namespace. The Cluster generator uses these Secrets to produce parameters:

• name - Cluster name
• nameNormalized - Name normalized to lowercase alphanumeric, ’-’ or ’.’
• server - Cluster API server URL
• project - The Secret’s ‘project’ field (defaults to empty)
• metadata.labels.<key> - Each label in the Secret
• metadata.annotations.<key> - Each annotation in the Secret

Basic Example

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters: {} # Automatically use all clusters defined within Argo CD
  template:
    metadata:
      name: '{{.name}}-guestbook'
    spec:
      project: "my-project"
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps/
        targetRevision: HEAD
        path: guestbook
      destination:
        server: '{{.server}}'
        namespace: guestbook

Label Selector

Target only specific clusters using label selectors:

spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters:
      selector:
        matchLabels:
          staging: "true"
        # Also supports matchExpressions
        #matchExpressions:
        #  - key: staging
        #    operator: In
        #    values:
        #      - "true"
  template:
    # ...

Pass Additional Values

Provide additional parameters based on cluster labels:

spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters:
      selector:
        matchLabels:
          type: 'staging'
      values:
        revision: HEAD # staging clusters use HEAD branch
  - clusters:
      selector:
        matchLabels:
          type: 'production'
      values:
        revision: stable # production uses stable branch
  template:
    metadata:
      name: '{{.name}}-guestbook'
    spec:
      project: "my-project"
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps/
        targetRevision: '{{.values.revision}}'
        path: guestbook
      destination:
        server: '{{.server}}'
        namespace: guestbook

The values. prefix is always prepended to values provided via generators.clusters.values field.

Filter by Kubernetes Version

Filter clusters based on their Kubernetes version:

spec:
  goTemplate: true
  generators:
  - clusters:
      selector:
        matchLabels:
          argocd.argoproj.io/kubernetes-version: 1.28

You must set the label argocd.argoproj.io/auto-label-cluster-info to true on the cluster secret for automatic version labeling.

Git Generator

The Git generator has two subtypes: directories and files.

Git generators are often used to allow developers to create Applications. If the project field is templated, the source must be controlled by admins.

Git Directory Generator

Generates parameters based on directory structure in a Git repository:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-addons
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - git:
      repoURL: https://github.com/argoproj/argo-cd.git
      revision: HEAD
      directories:
      - path: applicationset/examples/git-generator-directory/cluster-addons/*
  template:
    metadata:
      name: '{{.path.basename}}'
    spec:
      project: "my-project"
      source:
        repoURL: https://github.com/argoproj/argo-cd.git
        targetRevision: HEAD
        path: '{{.path.path}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{.path.basename}}'
      syncPolicy:
        syncOptions:
        - CreateNamespace=true

Generated Parameters:

• {{.path.path}} - Directory path matching the wildcard
• {{index .path.segments n}} - Path split into array elements
• {{.path.basename}} - Right-most directory name
• {{.path.basenameNormalized}} - Basename with unsupported characters replaced

Exclude Directories

Exclude specific directories from being scanned:

generators:
- git:
    repoURL: https://github.com/argoproj/argo-cd.git
    revision: HEAD
    directories:
    - path: applicationset/examples/git-generator-directory/excludes/cluster-addons/*
    - path: applicationset/examples/git-generator-directory/excludes/cluster-addons/exclude-helm-guestbook
      exclude: true

Exclude rules have higher priority than include rules. If a directory matches at least one exclude pattern, it will be excluded.

Git File Generator

Generates parameters from JSON/YAML files in a Git repository:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - git:
      repoURL: https://github.com/argoproj/argo-cd.git
      revision: HEAD
      files:
      - path: "applicationset/examples/git-generator-files-discovery/cluster-config/**/config.json"
  template:
    metadata:
      name: '{{.cluster.name}}-guestbook'
    spec:
      project: default
      source:
        repoURL: https://github.com/argoproj/argo-cd.git
        targetRevision: HEAD
        path: "applicationset/examples/git-generator-files-discovery/apps/guestbook"
      destination:
        server: '{{.cluster.address}}'
        namespace: guestbook

Example config.json:

{
  "aws_account": "123456",
  "asset_id": "11223344",
  "cluster": {
    "owner": "[e-mail]",
    "name": "engineering-dev",
    "address": "https://1.2.3.4"
  }
}

Generated Parameters:

aws_account: 123456
asset_id: 11223344
cluster.owner: [e-mail]
cluster.name: engineering-dev
cluster.address: https://1.2.3.4

Additionally provides:

• {{.path.path}} - Path to directory containing the config file
• {{index .path.segments n}} - Path split into array elements
• {{.path.basename}} - Directory basename
• {{.path.filename}} - Matched filename
• {{.path.filenameNormalized}} - Filename with unsupported characters replaced

Matrix Generator

The Matrix generator combines parameters from two child generators, creating every possible combination.

Common Use Cases

• SCM Provider + Cluster: Scan GitHub organization repositories and deploy to all clusters
• Git Files + List: Deploy applications from config files to a fixed list of clusters
• Git Directory + Cluster Decision Resource: Deploy applications from Git folders to clusters from a custom resource

Example: Git Directory + Cluster

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-git
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - matrix:
      generators:
      # Child generator #1: Git directories
      - git:
          repoURL: https://github.com/argoproj/argo-cd.git
          revision: HEAD
          directories:
          - path: applicationset/examples/matrix/cluster-addons/*
      # Child generator #2: Clusters
      - clusters:
          selector:
            matchLabels:
              argocd.argoproj.io/secret-type: cluster
  template:
    metadata:
      name: '{{.path.basename}}-{{.name}}'
    spec:
      project: '{{index .metadata.labels "environment"}}'
      source:
        repoURL: https://github.com/argoproj/argo-cd.git
        targetRevision: HEAD
        path: '{{.path.path}}'
      destination:
        server: '{{.server}}'
        namespace: '{{.path.basename}}'

This example:

1. Finds argo-workflows and prometheus-operator directories
2. Finds staging and production clusters
3. Generates 4 Applications: each app on each cluster

Using Parameters Between Generators

You can use parameters from one child generator in another:

generators:
- matrix:
    generators:
    - git:
        repoURL: https://github.com/argoproj/applicationset.git
        revision: HEAD
        files:
        - path: "cluster-config/**/config.json"
    - clusters:
        selector:
          matchLabels:
            argocd.argoproj.io/secret-type: cluster
            kubernetes.io/environment: '{{.path.basename}}' # Uses parameter from git generator

When using parameters from one child generator in another, the consuming generator must come after the producing generator.

Two Git Generators with pathParamPrefix

When using two Git generators, use pathParamPrefix to avoid parameter conflicts:

generators:
- matrix:
    generators:
    - git:
        repoURL: https://github.com/some-org/some-repo.git
        revision: HEAD
        files:
        - path: "apps/*.json"
        pathParamPrefix: app
    - git:
        repoURL: https://github.com/some-org/some-repo.git
        revision: HEAD
        files:
        - path: "targets/{{.appName}}/*.json"
        pathParamPrefix: target

Additional Generators

Merge Generator

Merges parameters from two or more generators. Additional generators can override base generator values.

SCM Provider

Uses GitHub/GitLab/Bitbucket APIs to automatically discover repositories within an organization.

Pull Request

Uses SCM provider APIs to automatically discover open pull requests within a repository.

Cluster Decision Resource

Interfaces with Kubernetes custom resources that use custom logic to decide which clusters to deploy to.

Plugin Generator

Makes RPC HTTP requests to external services to provide parameters.

Post Selector

All generators can be filtered using a Post Selector to further refine generated parameters:

generators:
- list:
    elements:
    - cluster: dev
      env: staging
    - cluster: prod
      env: production
    selector:
      matchLabels:
        env: production

Next Steps

Use Cases

Explore real-world patterns for cluster add-ons, monorepos, and self-service deployments