ApplicationSet Use Cases

Overview

With generators, the ApplicationSet controller provides powerful tools to automate the templating and modification of Argo CD Applications. Here are the primary use cases that ApplicationSet was designed to support.

Cluster Add-ons

An initial design focus of the ApplicationSet controller was to enable infrastructure teams to automatically create and manage a large set of Argo CD Applications across many clusters as a single unit.

The Problem

Infrastructure teams are responsible for provisioning cluster add-ons to multiple Kubernetes clusters:

Cluster add-ons are operators and controllers like:
- Prometheus operator for metrics
- Argo Workflows controller for workflow orchestration
- Cert-manager for certificate management
- Ingress controllers
Scale challenges:
- Organizations may manage tens, hundreds, or thousands of clusters
- New clusters are added/modified/removed regularly
- Different add-ons need to target different cluster subsets (staging vs production)
Permission requirements:
- Installing add-ons requires cluster-level permissions
- Development teams (cluster tenants) don’t have these permissions
- Infrastructure/ops teams need automation to scale

The Solution

The infrastructure team maintains a Git repository with application manifests for cluster add-ons. ApplicationSet automatically deploys these add-ons to target clusters.

Option 1: List Generator

Manually maintain a list of target clusters:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: prometheus-operator
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - list:
      elements:
      - cluster: engineering-dev
        url: https://dev.example.com
      - cluster: engineering-prod
        url: https://prod.example.com
  template:
    metadata:
      name: '{{.cluster}}-prometheus'
    spec:
      project: cluster-addons
      source:
        repoURL: https://github.com/infra-team/cluster-addons.git
        targetRevision: HEAD
        path: prometheus-operator
      destination:
        server: '{{.url}}'
        namespace: monitoring
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
        - CreateNamespace=true

Adding/removing clusters requires manually updating the ApplicationSet’s list elements.

Option 2: Cluster Generator (Recommended)

Automatically detect all clusters defined in Argo CD:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: prometheus-operator
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters:
      selector:
        matchLabels:
          environment: production
  template:
    metadata:
      name: '{{.name}}-prometheus'
    spec:
      project: cluster-addons
      source:
        repoURL: https://github.com/infra-team/cluster-addons.git
        targetRevision: HEAD
        path: prometheus-operator
      destination:
        server: '{{.server}}'
        namespace: monitoring
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
        - CreateNamespace=true

Adding/removing a cluster from Argo CD automatically creates/removes the corresponding Application.

Option 3: Git Generator

Most flexible approach using Git as the source of truth: Using files field:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-addons
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - git:
      repoURL: https://github.com/infra-team/cluster-config.git
      revision: HEAD
      files:
      - path: "clusters/**/config.json"
  template:
    metadata:
      name: '{{.cluster.name}}-prometheus'
    spec:
      project: cluster-addons
      source:
        repoURL: https://github.com/infra-team/cluster-addons.git
        targetRevision: HEAD
        path: prometheus-operator
      destination:
        server: '{{.cluster.address}}'
        namespace: monitoring

clusters/prod-us-east/config.json:

{
  "cluster": {
    "name": "prod-us-east",
    "address": "https://prod.us-east.example.com"
  }
}

Using directories field:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-addons
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - git:
      repoURL: https://github.com/infra-team/cluster-config.git
      revision: HEAD
      directories:
      - path: clusters/*
  template:
    metadata:
      name: '{{.path.basename}}-prometheus'
    spec:
      project: cluster-addons
      source:
        repoURL: https://github.com/infra-team/cluster-addons.git
        targetRevision: HEAD
        path: prometheus-operator
      destination:
        name: '{{.path.basename}}'
        namespace: monitoring

Monorepos

In the monorepo use case, cluster administrators manage the entire state of a Kubernetes cluster from a single Git repository.

The Problem

Single Git repository contains manifests for multiple applications
Changes to the repository should automatically deploy to the cluster
Need to avoid creating individual Application resources for each service manually
Want GitOps workflow where merging to main triggers deployment

The Solution

ApplicationSet automatically discovers applications in the monorepo and creates Application resources for each.

Git Directory Approach

Repository structure:

cluster-config/
├── argo-workflows/
│   ├── deployment.yaml
│   └── service.yaml
├── prometheus-operator/
│   └── values.yaml
├── cert-manager/
│   └── kustomization.yaml
└── backend-services/
    ├── api/
    │   └── deployment.yaml
    └── worker/
        └── deployment.yaml

ApplicationSet:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-apps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - git:
      repoURL: https://github.com/org/cluster-config.git
      revision: HEAD
      directories:
      - path: "*"
      - path: "backend-services/*"
  template:
    metadata:
      name: '{{.path.basename}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/cluster-config.git
        targetRevision: HEAD
        path: '{{.path.path}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{.path.basename}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
        - CreateNamespace=true

This creates Applications for argo-workflows, prometheus-operator, cert-manager, api, and worker.

Git Files Approach

Repository structure:

apps/
├── argo-workflows/
│   ├── config.json
│   └── manifests/
├── prometheus/
│   ├── config.json
│   └── manifests/
└── cert-manager/
    ├── config.json
    └── manifests/

apps/argo-workflows/config.json:

{
  "appName": "argo-workflows",
  "namespace": "workflows",
  "syncPolicy": "automated"
}

ApplicationSet:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-apps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - git:
      repoURL: https://github.com/org/cluster-config.git
      revision: HEAD
      files:
      - path: "apps/**/config.json"
  template:
    metadata:
      name: '{{.appName}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/cluster-config.git
        targetRevision: HEAD
        path: '{{.path.path}}/manifests'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{.namespace}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Self-Service Multi-Tenant Deployments

The self-service use case allows developers on multi-tenant Kubernetes clusters to deploy applications without requiring cluster administrator intervention.

The Problem

Developers want to:

Deploy multiple applications to a single cluster
Deploy to multiple clusters
Do so without involving cluster administrators for each deployment

Traditional app-of-apps approach issues:

Developers define Argo CD Application resources in Git
Admins review/accept via merge requests
Security risk: Application spec contains sensitive fields:
- project - controls permissions
- cluster - target cluster
- namespace - target namespace
Inadvertent merge could grant excessive permissions

The Solution

ApplicationSet allows admins to restrict sensitive fields while letting developers customize safe fields.

Safe Self-Service Pattern

Repository structure (developer-controlled):

apps/
├── team-a/
│   ├── frontend/
│   │   └── config.json
│   └── backend/
│       └── config.json
└── team-b/
    └── api/
        └── config.json

apps/team-a/frontend/config.json:

{
  "app": {
    "source": "https://github.com/team-a/frontend",
    "revision": "v1.2.3",
    "path": "k8s"
  }
}

ApplicationSet (admin-controlled):

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: team-apps
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - git:
      repoURL: https://github.com/org/app-configs.git
      revision: main
      files:
      - path: "apps/**/config.json"
  template:
    metadata:
      name: '{{.path.segments 1}}-{{.path.basename}}' # team-a-frontend
    spec:
      project: '{{.path.segments 1}}' # RESTRICTED: project based on team folder
      source:
        # CUSTOMIZABLE: developers control these via config.json
        repoURL: '{{.app.source}}'
        targetRevision: '{{.app.revision}}'
        path: '{{.app.path}}'
      destination:
        name: production-cluster # RESTRICTED: admins control target cluster
        namespace: '{{.path.segments 1}}' # RESTRICTED: namespace based on team folder
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Security benefits:

Developers can customize: source repo, revision, path
Admins control: target cluster, namespace, project
Developers cannot escalate privileges
Git commits only contain config.json, not full Application specs

Multi-Cluster Self-Service

Extend to multiple clusters using Matrix generator:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: team-apps-multi-cluster
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - matrix:
      generators:
      # Developer-controlled app configs
      - git:
          repoURL: https://github.com/org/app-configs.git
          revision: main
          files:
          - path: "apps/**/config.json"
      # Admin-controlled cluster list
      - list:
          elements:
          - cluster: staging
            url: https://staging.example.com
          - cluster: production
            url: https://production.example.com
  template:
    metadata:
      name: '{{.path.segments 1}}-{{.path.basename}}-{{.cluster}}'
    spec:
      project: '{{.path.segments 1}}'
      source:
        repoURL: '{{.app.source}}'
        targetRevision: '{{.app.revision}}'
        path: '{{.app.path}}'
      destination:
        server: '{{.url}}'
        namespace: '{{.path.segments 1}}'

This creates Applications for each app config on each cluster: team-a-frontend-staging, team-a-frontend-production, etc.

Multi-Cluster Deployment Patterns

Deploy Different Apps to Different Clusters

Use cluster labels to control which apps deploy where:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: selective-deployment
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - matrix:
      generators:
      - git:
          repoURL: https://github.com/org/apps.git
          revision: HEAD
          files:
          - path: "apps/**/config.json"
      - clusters:
          selector:
            matchLabels:
              argocd.argoproj.io/secret-type: cluster
              app-tier: '{{.tier}}' # Matches tier from config.json
  template:
    metadata:
      name: '{{.name}}-{{.appName}}'
    spec:
      project: default
      source:
        repoURL: '{{.source}}'
        targetRevision: HEAD
        path: '{{.path}}'
      destination:
        server: '{{.server}}'
        namespace: '{{.namespace}}'

Progressive Rollout Across Clusters

Deploy to dev, then staging, then production:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: progressive-rollout
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - clusters:
      selector:
        matchLabels:
          environment: dev
      values:
        revision: main
  - clusters:
      selector:
        matchLabels:
          environment: staging
      values:
        revision: release-candidate
  - clusters:
      selector:
        matchLabels:
          environment: production
      values:
        revision: stable
  template:
    metadata:
      name: '{{.name}}-myapp'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/myapp.git
        targetRevision: '{{.values.revision}}'
        path: k8s
      destination:
        server: '{{.server}}'
        namespace: myapp

Best Practices

Start Simple with List/Cluster Generators

Begin with List or Cluster generators before moving to more complex Git-based generators. This helps you understand the fundamentals.

Use Automated Sync Policies

Enable automated sync with prune and selfHeal for true GitOps:

syncPolicy:
  automated:
    prune: true
    selfHeal: true

Leverage Cluster Labels

Use cluster labels extensively for flexible targeting:

environment: production/staging/dev
region: us-east/us-west/eu
tier: frontend/backend/data

Control Sensitive Fields in Self-Service

Always hard-code project, destination.server, and destination.namespace when allowing developer customization.

Use Matrix for Combinations

When you need to deploy multiple apps to multiple clusters, Matrix generator eliminates duplication.

Get Started

Installation

Core Features

Configuration

Application Management

ApplicationSet

Manifest Sources

Operations

Security

ApplicationSet Use Cases

Overview

Cluster Add-ons

The Problem

The Solution

Option 1: List Generator

Option 2: Cluster Generator (Recommended)

Option 3: Git Generator

Monorepos

The Problem

The Solution

Git Directory Approach

Git Files Approach

Self-Service Multi-Tenant Deployments

The Problem

The Solution

Safe Self-Service Pattern

Multi-Cluster Self-Service

Multi-Cluster Deployment Patterns

Deploy Different Apps to Different Clusters

Progressive Rollout Across Clusters

Best Practices

Next Steps

Generators

Security

Get Started

Installation

Core Features

Configuration

Application Management

ApplicationSet

Manifest Sources

Operations

Security

​Overview

​Cluster Add-ons

​The Problem

​The Solution

​Option 1: List Generator

​Option 2: Cluster Generator (Recommended)

​Option 3: Git Generator

​Monorepos

​The Problem

​The Solution

​Git Directory Approach

​Git Files Approach

​Self-Service Multi-Tenant Deployments

​The Problem

​The Solution

​Safe Self-Service Pattern

​Multi-Cluster Self-Service

​Multi-Cluster Deployment Patterns

​Deploy Different Apps to Different Clusters

​Progressive Rollout Across Clusters

​Best Practices

​Next Steps

Generators

Security

Overview

Cluster Add-ons

The Problem

The Solution

Option 1: List Generator

Option 2: Cluster Generator (Recommended)

Option 3: Git Generator

Monorepos

The Problem

The Solution

Git Directory Approach

Git Files Approach

Self-Service Multi-Tenant Deployments

The Problem

The Solution

Safe Self-Service Pattern

Multi-Cluster Self-Service

Multi-Cluster Deployment Patterns

Deploy Different Apps to Different Clusters

Progressive Rollout Across Clusters

Best Practices

Next Steps