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

generators · ApplicationSetGenerator[] · required

List of generators that produce parameters for the template

Show Generator types

list · ListGenerator

Static list of parameter sets

clusters · ClusterGenerator

Generate from registered clusters

git · GitGenerator

Generate from Git repository contents

matrix · MatrixGenerator

Combine multiple generators

merge · MergeGenerator

Merge parameters from multiple generators

scmProvider · SCMProviderGenerator

Generate from SCM provider (GitHub, GitLab, etc.)

pullRequest · PullRequestGenerator

Generate from pull requests

template · ApplicationSetTemplate · required

Template for generating Applications

Show ApplicationSetTemplate fields

metadata · ApplicationSetTemplateMeta

Metadata template (name, labels, annotations)

spec · ApplicationSpec · required

Application spec template

syncPolicy · ApplicationSetSyncPolicy

Sync policy for generated applications

Show ApplicationSetSyncPolicy fields

preserveResourcesOnDeletion · boolean

Keep applications when ApplicationSet is deleted

applicationsSync · string

Sync policy: “create-only”, “create-update”, “create-delete”, “sync”

strategy · ApplicationSetStrategy

Progressive rollout strategy

Show ApplicationSetStrategy fields

type · string

Strategy type (e.g., “RollingSync”)

rollingSync · ApplicationSetRolloutStrategy

Rolling sync configuration with steps

goTemplate · boolean

Use Go template syntax instead of fasttemplate (default: false)

Example ApplicationSet

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.

GET /api/v1/applicationsets

projects · string[]

Filter by project names

selector · string

Label selector

appsetNamespace · string

ApplicationSet namespace (default: argocd control plane namespace)

cURL

curl https://argocd-server/api/v1/applicationsets \
  -H "Authorization: Bearer $TOKEN"

Get ApplicationSet

Retrieve a specific ApplicationSet.

GET /api/v1/applicationsets/{name}

name · string · required

ApplicationSet name

appsetNamespace · string

ApplicationSet namespace

cURL

curl https://argocd-server/api/v1/applicationsets/guestbook-clusters \
  -H "Authorization: Bearer $TOKEN"

Create ApplicationSet

Create a new ApplicationSet.

POST /api/v1/applicationsets

applicationset · ApplicationSet · required

Complete ApplicationSet resource

upsert · boolean

Update if already exists (default: false)

dryRun · boolean

Validate without creating (default: false)

cURL

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"
          }
        }
      }
    }
  }'

Delete ApplicationSet

Delete an ApplicationSet.

DELETE /api/v1/applicationsets/{name}

name · string · required

ApplicationSet name

appsetNamespace · string

ApplicationSet namespace

cURL

curl -X DELETE https://argocd-server/api/v1/applicationsets/guestbook-clusters \
  -H "Authorization: Bearer $TOKEN"

Generator Operations

Generate Applications

Preview applications that would be generated by an ApplicationSet.

POST /api/v1/applicationsets/generate

applicationSet · ApplicationSet · required

ApplicationSet to evaluate

Example Request:

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:

applications · Application[]

List of generated Application resources

Monitoring Operations

Get Resource Tree

Get the ApplicationSet’s resource hierarchy.

GET /api/v1/applicationsets/{name}/resource-tree

name · string · required

ApplicationSet name

appsetNamespace · string

ApplicationSet namespace

List Events

List Kubernetes events for the ApplicationSet.

GET /api/v1/applicationsets/{name}/events

name · string · required

ApplicationSet name

Watch ApplicationSets

Stream ApplicationSet change events.

GET /api/v1/stream/applicationsets

projects · string[]

Filter by projects

selector · string

Label selector

resourceVersion · string

Start watching from specific resource version

Generator Examples

List Generator

generators:
- list:
    elements:
    - cluster: prod
      url: https://prod.example.com
    - cluster: staging
      url: https://staging.example.com

Cluster Generator

generators:
- clusters:
    selector:
      matchLabels:
        env: production
      matchExpressions:
      - key: region
        operator: In
        values: [us-east, us-west]

Git Directory Generator

generators:
- git:
    repoURL: https://github.com/myorg/myrepo
    revision: HEAD
    directories:
    - path: apps/*

Git Files Generator

generators:
- git:
    repoURL: https://github.com/myorg/myrepo
    revision: HEAD
    files:
    - path: "configs/*.json"

Matrix Generator

generators:
- matrix:
    generators:
    - git:
        repoURL: https://github.com/myorg/myrepo
        directories:
        - path: apps/*
    - clusters:
        selector:
          matchLabels:
            env: production

SCM Provider Generator

generators:
- scmProvider:
    github:
      organization: myorg
      tokenRef:
        secretName: github-token
        key: token
    filters:
    - repositoryMatch: "^app-.*"

Pull Request Generator

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:

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

Application API

Manage generated Applications

Cluster API

Register clusters for generators