> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## List Generator

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

### Basic Example

```yaml theme={null}
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
```

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

### Flexible Key/Value Pairs

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

```yaml theme={null}
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:

```yaml theme={null}
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

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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
```

<Note>
  The `values.` prefix is always prepended to values provided via `generators.clusters.values` field.
</Note>

### Filter by Kubernetes Version

Filter clusters based on their Kubernetes version:

```yaml theme={null}
spec:
  goTemplate: true
  generators:
  - clusters:
      selector:
        matchLabels:
          argocd.argoproj.io/kubernetes-version: 1.28
```

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

## Git Generator

The Git generator has two subtypes: **directories** and **files**.

<Warning>
  Git generators are often used to allow developers to create Applications. If the `project` field is templated, [the source must be controlled by admins](/applicationset/security#templated-project-field).
</Warning>

### Git Directory Generator

Generates parameters based on directory structure in a Git repository:

```yaml theme={null}
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:

```yaml theme={null}
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
```

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

### Git File Generator

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

```yaml theme={null}
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:**

```json theme={null}
{
  "aws_account": "123456",
  "asset_id": "11223344",
  "cluster": {
    "owner": "cluster-admin@company.com",
    "name": "engineering-dev",
    "address": "https://1.2.3.4"
  }
}
```

**Generated Parameters:**

```text theme={null}
aws_account: 123456
asset_id: 11223344
cluster.owner: cluster-admin@company.com
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

```yaml theme={null}
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:

```yaml theme={null}
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
```

<Note>
  When using parameters from one child generator in another, the consuming generator **must come after** the producing generator.
</Note>

### Two Git Generators with pathParamPrefix

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

```yaml theme={null}
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

<CardGroup cols={2}>
  <Card title="Merge Generator" icon="code-merge">
    Merges parameters from two or more generators. Additional generators can override base generator values.
  </Card>

  <Card title="SCM Provider" icon="github">
    Uses GitHub/GitLab/Bitbucket APIs to automatically discover repositories within an organization.
  </Card>

  <Card title="Pull Request" icon="code-pull-request">
    Uses SCM provider APIs to automatically discover open pull requests within a repository.
  </Card>

  <Card title="Cluster Decision Resource" icon="cube">
    Interfaces with Kubernetes custom resources that use custom logic to decide which clusters to deploy to.
  </Card>

  <Card title="Plugin Generator" icon="puzzle-piece">
    Makes RPC HTTP requests to external services to provide parameters.
  </Card>
</CardGroup>

## Post Selector

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

```yaml theme={null}
generators:
- list:
    elements:
    - cluster: dev
      env: staging
    - cluster: prod
      env: production
    selector:
      matchLabels:
        env: production
```

## Next Steps

<Card title="Use Cases" icon="lightbulb" href="/applicationset/use-cases">
  Explore real-world patterns for cluster add-ons, monorepos, and self-service deployments
</Card>