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

# ApplicationSets

> Automate generation of Argo CD Applications with the ApplicationSet controller

The ApplicationSet controller automates the generation of Argo CD Applications, improving multi-cluster and multi-tenant support. It enables templating Applications from various sources and allows developers to independently create Applications without cluster-administrator intervention.

## Overview

ApplicationSet is a Kubernetes Custom Resource that automatically generates Argo CD Applications based on defined generators and templates.

<Warning>
  Be aware of the [security implications](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Security/) before allowing developers to create Applications via ApplicationSets.
</Warning>

## Basic ApplicationSet

```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://1.2.3.4
          - cluster: engineering-prod
            url: https://2.4.6.8
  template:
    metadata:
      name: '{{.cluster}}-guestbook'
    spec:
      project: my-project
      source:
        repoURL: https://github.com/infra-team/cluster-deployments.git
        targetRevision: HEAD
        path: guestbook/{{.cluster}}
      destination:
        server: '{{.url}}'
        namespace: guestbook
```

This ApplicationSet generates multiple Applications (one per cluster) from a single resource definition.

## Generators

Generators provide parameters that are rendered into the Application template. ApplicationSet supports multiple generator types:

### List Generator

Provides a fixed list of parameters:

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

### Cluster Generator

Automatically discovers clusters registered in Argo CD:

```yaml theme={null}
generators:
  - clusters:
      selector:
        matchLabels:
          environment: production
      values:
        revision: main
```

### Git Generator

Generates Applications based on Git repository contents:

<Tabs>
  <Tab title="Directory-based">
    ```yaml theme={null}
    generators:
      - git:
          repoURL: https://github.com/org/repo.git
          revision: HEAD
          directories:
            - path: apps/*
    ```
  </Tab>

  <Tab title="File-based">
    ```yaml theme={null}
    generators:
      - git:
          repoURL: https://github.com/org/repo.git
          revision: HEAD
          files:
            - path: "clusters/*.json"
    ```
  </Tab>
</Tabs>

### SCM Provider Generator

Automatically discovers repositories from SCM providers (GitHub, GitLab, Bitbucket, etc.):

```yaml theme={null}
generators:
  - scmProvider:
      github:
        organization: myorg
        allBranches: false
      filters:
        - repositoryMatch: ^app-.*
```

### Pull Request Generator

Creates temporary preview environments for pull requests:

```yaml theme={null}
generators:
  - pullRequest:
      github:
        owner: myorg
        repo: myrepo
        labels:
          - preview
```

### Matrix Generator

Generates the cartesian product of two generators:

```yaml theme={null}
generators:
  - matrix:
      generators:
        - list:
            elements:
              - cluster: dev
              - cluster: prod
        - list:
            elements:
              - app: frontend
              - app: backend
# Produces: dev-frontend, dev-backend, prod-frontend, prod-backend
```

### Merge Generator

Merges parameters from multiple generators:

```yaml theme={null}
generators:
  - merge:
      generators:
        - clusters:
            selector:
              matchLabels:
                type: production
        - list:
            elements:
              - cluster: special-cluster
                special: true
      mergeKeys:
        - server
```

## Template Configuration

The template defines the Application structure:

```yaml theme={null}
template:
  metadata:
    name: '{{.name}}'
    labels:
      environment: '{{.environment}}'
    annotations:
      managed-by: applicationset
  spec:
    project: '{{.project}}'
    source:
      repoURL: '{{.repoUrl}}'
      targetRevision: '{{.revision}}'
      path: '{{.path}}'
    destination:
      server: '{{.server}}'
      namespace: '{{.namespace}}'
    syncPolicy:
      automated:
        prune: true
        selfHeal: true
```

## Go Template Support

Enable Go templating for advanced use cases:

```yaml theme={null}
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
    - list:
        elements:
          - name: app1
            replicas: 3
  template:
    metadata:
      name: '{{.name}}'
    spec:
      source:
        helm:
          parameters:
            - name: replicas
              value: '{{.replicas}}'
```

## Sync Policy

Control how ApplicationSet manages generated Applications:

```yaml theme={null}
spec:
  syncPolicy:
    # Preserve Applications when ApplicationSet is deleted
    preserveResourcesOnDeletion: true
    
    # Control Application lifecycle
    applicationsSync: sync  # or create-only, create-update, create-delete
```

| Policy           | Create | Update | Delete |
| ---------------- | ------ | ------ | ------ |
| `create-only`    | ✓      | ✗      | ✗      |
| `create-update`  | ✓      | ✓      | ✗      |
| `create-delete`  | ✓      | ✗      | ✓      |
| `sync` (default) | ✓      | ✓      | ✓      |

## Progressive Sync (Rollout Strategy)

Deploy Applications in a controlled sequence:

```yaml theme={null}
spec:
  strategy:
    type: RollingSync
    rollingSync:
      steps:
        - matchExpressions:
            - key: environment
              operator: In
              values:
                - dev
          maxUpdate: 1
        - matchExpressions:
            - key: environment
              operator: In
              values:
                - staging
          maxUpdate: 2
        - matchExpressions:
            - key: environment
              operator: In
              values:
                - prod
          maxUpdate: 100%
```

## Ignore Application Differences

Prevent ApplicationSet from overwriting certain Application fields:

```yaml theme={null}
spec:
  ignoreApplicationDifferences:
    - jsonPointers:
        - /spec/syncPolicy
      # Applies to all Applications
    - name: specific-app
      jqPathExpressions:
        - .spec.source.helm.parameters
```

## Preserved Fields

Preserve annotations and labels on generated Applications:

```yaml theme={null}
spec:
  preservedFields:
    annotations:
      - notifications.argoproj.io/*
      - custom.annotation.io/*
    labels:
      - team
      - cost-center
```

## Template Patch

Apply patches to the base template:

```yaml theme={null}
spec:
  template:
    # Base template
    spec:
      project: default
  templatePatch: |
    spec:
      project: '{{ .project }}'
      {{- if eq .environment "prod" }}
      syncPolicy:
        automated:
          prune: false
      {{- end }}
```

## Selectors

Filter generator output using label selectors:

```yaml theme={null}
generators:
  - clusters:
      selector:
        matchLabels:
          environment: production
        matchExpressions:
          - key: region
            operator: In
            values:
              - us-east-1
              - us-west-2
  - list:
      elements:
        - name: app1
          labels:
            tier: frontend
        - name: app2
          labels:
            tier: backend
    selector:
      matchLabels:
        tier: frontend
```

## Multi-Tenancy with ApplicationSets

ApplicationSets enable self-service application creation:

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: team-apps
spec:
  generators:
    - git:
        repoURL: https://github.com/teams/team-repos.git
        revision: HEAD
        files:
          - path: "teams/*/config.json"
  template:
    metadata:
      name: '{{.team}}-{{.app}}'
    spec:
      project: '{{.team}}'
      source:
        repoURL: '{{.repo}}'
        targetRevision: '{{.branch}}'
        path: '{{.path}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{.team}}-{{.environment}}'
```

## Status and Conditions

ApplicationSet maintains status information:

```yaml theme={null}
status:
  conditions:
    - type: ResourcesUpToDate
      status: "True"
      reason: ApplicationSetUpToDate
      message: All generated Applications are up to date
  applicationStatus:
    - application: dev-frontend
      lastTransitionTime: "2024-01-15T10:30:00Z"
      status: Healthy
    - application: prod-backend
      lastTransitionTime: "2024-01-15T10:32:00Z"
      status: Progressing
```

## Example Use Cases

<AccordionGroup>
  <Accordion title="Deploy to multiple clusters">
    Use the Cluster generator to deploy the same application to all clusters matching a label selector.
  </Accordion>

  <Accordion title="Monorepo multi-app deployment">
    Use the Git directory generator to automatically create Applications for each directory in a repository.
  </Accordion>

  <Accordion title="PR preview environments">
    Use the Pull Request generator to automatically create preview environments for each pull request.
  </Accordion>

  <Accordion title="Multi-tenant application management">
    Combine Git file generator with team configurations to allow teams to self-manage their applications.
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Use specific generators" icon="target">
    Choose the most appropriate generator for your use case to simplify configuration
  </Card>

  <Card title="Enable Go templates" icon="code">
    Use `goTemplate: true` for advanced templating capabilities
  </Card>

  <Card title="Implement progressive sync" icon="forward">
    Use rollout strategies for production deployments
  </Card>

  <Card title="Set sync policies" icon="gear">
    Configure appropriate sync policies to control Application lifecycle
  </Card>
</CardGroup>

<Card title="Next Steps" icon="arrow-right" href="/features/projects">
  Learn about AppProjects for multi-tenancy and access control
</Card>