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

> CRUD operations for ApplicationSet resources and generator management

## Overview

The ApplicationSet Service API manages ApplicationSet resources, which automatically generate multiple Applications from templates using generators.

**Base Path:** `/api/v1/applicationsets`

**gRPC Service:** `applicationset.ApplicationSetService`

## ApplicationSet Resource

An ApplicationSet uses generators to create multiple Application resources from a single template.

### ApplicationSet Spec

<ParamField path="generators" type="ApplicationSetGenerator[]" required>
  List of generators that produce parameters for the template

  <Expandable title="Generator types">
    <ResponseField name="list" type="ListGenerator">
      Static list of parameter sets
    </ResponseField>

    <ResponseField name="clusters" type="ClusterGenerator">
      Generate from registered clusters
    </ResponseField>

    <ResponseField name="git" type="GitGenerator">
      Generate from Git repository contents
    </ResponseField>

    <ResponseField name="matrix" type="MatrixGenerator">
      Combine multiple generators
    </ResponseField>

    <ResponseField name="merge" type="MergeGenerator">
      Merge parameters from multiple generators
    </ResponseField>

    <ResponseField name="scmProvider" type="SCMProviderGenerator">
      Generate from SCM provider (GitHub, GitLab, etc.)
    </ResponseField>

    <ResponseField name="pullRequest" type="PullRequestGenerator">
      Generate from pull requests
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="template" type="ApplicationSetTemplate" required>
  Template for generating Applications

  <Expandable title="ApplicationSetTemplate fields">
    <ResponseField name="metadata" type="ApplicationSetTemplateMeta">
      Metadata template (name, labels, annotations)
    </ResponseField>

    <ResponseField name="spec" type="ApplicationSpec" required>
      Application spec template
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="syncPolicy" type="ApplicationSetSyncPolicy">
  Sync policy for generated applications

  <Expandable title="ApplicationSetSyncPolicy fields">
    <ResponseField name="preserveResourcesOnDeletion" type="boolean">
      Keep applications when ApplicationSet is deleted
    </ResponseField>

    <ResponseField name="applicationsSync" type="string">
      Sync policy: "create-only", "create-update", "create-delete", "sync"
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="strategy" type="ApplicationSetStrategy">
  Progressive rollout strategy

  <Expandable title="ApplicationSetStrategy fields">
    <ResponseField name="type" type="string">
      Strategy type (e.g., "RollingSync")
    </ResponseField>

    <ResponseField name="rollingSync" type="ApplicationSetRolloutStrategy">
      Rolling sync configuration with steps
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="goTemplate" type="boolean">
  Use Go template syntax instead of fasttemplate (default: false)
</ParamField>

### Example ApplicationSet

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook-clusters
  namespace: argocd
spec:
  generators:
  - clusters:
      selector:
        matchLabels:
          env: production
  template:
    metadata:
      name: '{{name}}-guestbook'
    spec:
      project: default
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps
        targetRevision: HEAD
        path: guestbook
      destination:
        server: '{{server}}'
        namespace: guestbook
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
```

## API Operations

### List ApplicationSets

Retrieve a list of ApplicationSets.

```bash theme={null}
GET /api/v1/applicationsets
```

<ParamField query="projects" type="string[]">
  Filter by project names
</ParamField>

<ParamField query="selector" type="string">
  Label selector
</ParamField>

<ParamField query="appsetNamespace" type="string">
  ApplicationSet namespace (default: argocd control plane namespace)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://argocd-server/api/v1/applicationsets \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```go Go theme={null}
  import applicationsetpkg "github.com/argoproj/argo-cd/v3/pkg/apiclient/applicationset"

  appsetClient := applicationsetpkg.NewApplicationSetServiceClient(conn)
  appsets, err := appsetClient.List(ctx, &applicationsetpkg.ApplicationSetListQuery{
      Projects: []string{"default"},
  })
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://argocd-server/api/v1/applicationsets",
      headers={"Authorization": f"Bearer {token}"}
  )
  appsets = response.json()
  ```
</CodeGroup>

### Get ApplicationSet

Retrieve a specific ApplicationSet.

```bash theme={null}
GET /api/v1/applicationsets/{name}
```

<ParamField path="name" type="string" required>
  ApplicationSet name
</ParamField>

<ParamField query="appsetNamespace" type="string">
  ApplicationSet namespace
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://argocd-server/api/v1/applicationsets/guestbook-clusters \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```go Go theme={null}
  appset, err := appsetClient.Get(ctx, &applicationsetpkg.ApplicationSetGetQuery{
      Name: "guestbook-clusters",
  })
  ```
</CodeGroup>

### Create ApplicationSet

Create a new ApplicationSet.

```bash theme={null}
POST /api/v1/applicationsets
```

<ParamField body="applicationset" type="ApplicationSet" required>
  Complete ApplicationSet resource
</ParamField>

<ParamField body="upsert" type="boolean">
  Update if already exists (default: false)
</ParamField>

<ParamField body="dryRun" type="boolean">
  Validate without creating (default: false)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://argocd-server/api/v1/applicationsets \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "metadata": {
        "name": "guestbook-clusters"
      },
      "spec": {
        "generators": [
          {
            "clusters": {
              "selector": {
                "matchLabels": {
                  "env": "production"
                }
              }
            }
          }
        ],
        "template": {
          "metadata": {
            "name": "{{name}}-guestbook"
          },
          "spec": {
            "project": "default",
            "source": {
              "repoURL": "https://github.com/argoproj/argocd-example-apps",
              "path": "guestbook",
              "targetRevision": "HEAD"
            },
            "destination": {
              "server": "{{server}}",
              "namespace": "guestbook"
            }
          }
        }
      }
    }'
  ```

  ```go Go theme={null}
  appset, err := appsetClient.Create(ctx, &applicationsetpkg.ApplicationSetCreateRequest{
      Applicationset: &v1alpha1.ApplicationSet{
          ObjectMeta: metav1.ObjectMeta{
              Name: "guestbook-clusters",
          },
          Spec: v1alpha1.ApplicationSetSpec{
              Generators: []v1alpha1.ApplicationSetGenerator{
                  {
                      Clusters: &v1alpha1.ClusterGenerator{
                          Selector: metav1.LabelSelector{
                              MatchLabels: map[string]string{
                                  "env": "production",
                              },
                          },
                      },
                  },
              },
              Template: v1alpha1.ApplicationSetTemplate{
                  ApplicationSetTemplateMeta: v1alpha1.ApplicationSetTemplateMeta{
                      Name: "{{name}}-guestbook",
                  },
                  Spec: v1alpha1.ApplicationSpec{
                      Project: "default",
                      Source: &v1alpha1.ApplicationSource{
                          RepoURL:        "https://github.com/argoproj/argocd-example-apps",
                          Path:           "guestbook",
                          TargetRevision: "HEAD",
                      },
                      Destination: v1alpha1.ApplicationDestination{
                          Server:    "{{server}}",
                          Namespace: "guestbook",
                      },
                  },
              },
          },
      },
  })
  ```

  ```yaml YAML (via kubectl) theme={null}
  kubectl apply -f - <<EOF
  apiVersion: argoproj.io/v1alpha1
  kind: ApplicationSet
  metadata:
    name: guestbook-clusters
    namespace: argocd
  spec:
    generators:
    - clusters:
        selector:
          matchLabels:
            env: production
    template:
      metadata:
        name: '{{name}}-guestbook'
      spec:
        project: default
        source:
          repoURL: https://github.com/argoproj/argocd-example-apps
          targetRevision: HEAD
          path: guestbook
        destination:
          server: '{{server}}'
          namespace: guestbook
  EOF
  ```
</CodeGroup>

### Delete ApplicationSet

Delete an ApplicationSet.

```bash theme={null}
DELETE /api/v1/applicationsets/{name}
```

<ParamField path="name" type="string" required>
  ApplicationSet name
</ParamField>

<ParamField query="appsetNamespace" type="string">
  ApplicationSet namespace
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://argocd-server/api/v1/applicationsets/guestbook-clusters \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```go Go theme={null}
  _, err := appsetClient.Delete(ctx, &applicationsetpkg.ApplicationSetDeleteRequest{
      Name: "guestbook-clusters",
  })
  ```
</CodeGroup>

## Generator Operations

### Generate Applications

Preview applications that would be generated by an ApplicationSet.

```bash theme={null}
POST /api/v1/applicationsets/generate
```

<ParamField body="applicationSet" type="ApplicationSet" required>
  ApplicationSet to evaluate
</ParamField>

**Example Request:**

```bash theme={null}
curl -X POST https://argocd-server/api/v1/applicationsets/generate \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "applicationSet": {
      "metadata": {"name": "test"},
      "spec": {
        "generators": [{"list": {"elements": [{"cluster": "prod"}]}}],
        "template": {
          "metadata": {"name": "{{cluster}}-app"},
          "spec": {"project": "default"}
        }
      }
    }
  }'
```

**Response:**

<ResponseField name="applications" type="Application[]">
  List of generated Application resources
</ResponseField>

## Monitoring Operations

### Get Resource Tree

Get the ApplicationSet's resource hierarchy.

```bash theme={null}
GET /api/v1/applicationsets/{name}/resource-tree
```

<ParamField path="name" type="string" required>
  ApplicationSet name
</ParamField>

<ParamField query="appsetNamespace" type="string">
  ApplicationSet namespace
</ParamField>

### List Events

List Kubernetes events for the ApplicationSet.

```bash theme={null}
GET /api/v1/applicationsets/{name}/events
```

<ParamField path="name" type="string" required>
  ApplicationSet name
</ParamField>

### Watch ApplicationSets

Stream ApplicationSet change events.

```bash theme={null}
GET /api/v1/stream/applicationsets
```

<ParamField query="projects" type="string[]">
  Filter by projects
</ParamField>

<ParamField query="selector" type="string">
  Label selector
</ParamField>

<ParamField query="resourceVersion" type="string">
  Start watching from specific resource version
</ParamField>

## Generator Examples

### List Generator

```yaml theme={null}
generators:
- list:
    elements:
    - cluster: prod
      url: https://prod.example.com
    - cluster: staging
      url: https://staging.example.com
```

### Cluster Generator

```yaml theme={null}
generators:
- clusters:
    selector:
      matchLabels:
        env: production
      matchExpressions:
      - key: region
        operator: In
        values: [us-east, us-west]
```

### Git Directory Generator

```yaml theme={null}
generators:
- git:
    repoURL: https://github.com/myorg/myrepo
    revision: HEAD
    directories:
    - path: apps/*
```

### Git Files Generator

```yaml theme={null}
generators:
- git:
    repoURL: https://github.com/myorg/myrepo
    revision: HEAD
    files:
    - path: "configs/*.json"
```

### Matrix Generator

```yaml theme={null}
generators:
- matrix:
    generators:
    - git:
        repoURL: https://github.com/myorg/myrepo
        directories:
        - path: apps/*
    - clusters:
        selector:
          matchLabels:
            env: production
```

### SCM Provider Generator

```yaml theme={null}
generators:
- scmProvider:
    github:
      organization: myorg
      tokenRef:
        secretName: github-token
        key: token
    filters:
    - repositoryMatch: "^app-.*"
```

### Pull Request Generator

```yaml theme={null}
generators:
- pullRequest:
    github:
      owner: myorg
      repo: myrepo
      tokenRef:
        secretName: github-token
        key: token
    filters:
    - branchMatch: "^feature/.*"
```

## Template Variables

Common template variables available in ApplicationSet templates:

### Cluster Generator Variables

* `{{name}}` - Cluster name
* `{{server}}` - Cluster API server URL
* `{{metadata.labels.*}}` - Cluster labels
* `{{metadata.annotations.*}}` - Cluster annotations

### Git Generator Variables

* `{{path}}` - Directory or file path
* `{{path.basename}}` - Base name of path
* `{{path.filename}}` - File name (files generator)
* `{{path[n]}}` - Path segment at index n

### List Generator Variables

All fields from element objects are available as variables.

## Progressive Sync

Configure progressive rollout of generated applications:

```yaml theme={null}
strategy:
  type: RollingSync
  rollingSync:
    steps:
    - matchExpressions:
      - key: env
        operator: In
        values: [canary]
      maxUpdate: 1
    - matchExpressions:
      - key: env
        operator: In
        values: [production]
      maxUpdate: 25%
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Application API" icon="rocket" href="/api/application">
    Manage generated Applications
  </Card>

  <Card title="Cluster API" icon="server" href="/api/cluster">
    Register clusters for generators
  </Card>
</CardGroup>