TL;DR

ArgoCD ApplicationSets erzeugen automatisch ArgoCD Applications aus Templates und Generatoren. Statt 50 Application-YAMLs zu pflegen, definierst du ein Template mit einem Generator — etwa für jedes Verzeichnis im Repo oder jeden registrierten Cluster. Das skaliert GitOps von einem auf hunderte Apps.

ApplicationSets: ArgoCD skalieren

Eine ArgoCD Application verwaltet ein Deployment. Bei zehn Microservices in drei Umgebungen sind das 30 Application-Manifeste. ApplicationSets lösen dieses Problem mit einem Template-Ansatz: Ein Generator liefert Parameter, ein Template erzeugt daraus Applications.

# Statt 30 einzelner Applications — ein ApplicationSet
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: microservices
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://github.com/org/k8s-apps.git
        revision: HEAD
        directories:
          - path: apps/*
  template:
    metadata:
      name: '{{path.basename}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/k8s-apps.git
        targetRevision: HEAD
        path: '{{path}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{path.basename}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Dieses ApplicationSet erzeugt eine Application pro Unterverzeichnis in apps/. Neue Services werden automatisch deployed, sobald ein Verzeichnis hinzugefügt wird.

Git Generator: Directory

Der Directory Generator scannt ein Git-Repository nach Verzeichnissen. Ideal für Mono-Repos mit einer App pro Ordner.

Repo-Struktur

k8s-apps/
├── apps/
│   ├── frontend/
│   │   ├── deployment.yaml
│   │   └── service.yaml
│   ├── backend-api/
│   │   ├── deployment.yaml
│   │   └── service.yaml
│   └── worker/
│       └── kustomization.yaml

Jedes Verzeichnis unter apps/ wird zu einer eigenen Application. Du kannst Verzeichnisse ausschließen:

generators:
  - git:
      repoURL: https://github.com/org/k8s-apps.git
      revision: HEAD
      directories:
        - path: apps/*
        - path: apps/experimental
          exclude: true

Git Generator: Files

Der File Generator liest JSON- oder YAML-Dateien und nutzt deren Inhalt als Parameter. Damit steuerst du Deployments über Konfigurationsdateien.

// apps/frontend/config.json
{
  "appName": "frontend",
  "namespace": "web",
  "replicaCount": "3",
  "imageTag": "v2.4.1"
}

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: apps-from-files
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://github.com/org/k8s-apps.git
        revision: HEAD
        files:
          - path: "apps/*/config.json"
  template:
    metadata:
      name: '{{appName}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/k8s-apps.git
        targetRevision: HEAD
        path: 'charts/{{appName}}'
        helm:
          parameters:
            - name: replicaCount
              value: '{{replicaCount}}'
            - name: image.tag
              value: '{{imageTag}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{namespace}}'

Der Vorteil gegenüber dem Directory Generator: Du hast volle Kontrolle über die Parameter, ohne die Verzeichnisstruktur anzupassen.

Cluster Generator

Der Cluster Generator erstellt eine Application pro registriertem ArgoCD-Cluster. Perfekt für Multi-Cluster-Setups, wo dieselbe Infrastruktur überall laufen soll.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: monitoring-stack
  namespace: argocd
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            environment: production
  template:
    metadata:
      name: 'monitoring-{{name}}'
    spec:
      project: infrastructure
      source:
        repoURL: https://github.com/org/infra.git
        targetRevision: HEAD
        path: monitoring/
      destination:
        server: '{{server}}'
        namespace: monitoring
      syncPolicy:
        automated:
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

Neue Cluster registrieren und labeln — das Monitoring-Stack wird automatisch deployed:

# Cluster zu ArgoCD hinzufügen
argocd cluster add prod-eu-west --name prod-eu-west
argocd cluster add prod-us-east --name prod-us-east

# Labels setzen
kubectl label secret prod-eu-west -n argocd environment=production
kubectl label secret prod-us-east -n argocd environment=production

Matrix Generator

Der Matrix Generator kombiniert zwei Generatoren und bildet das kartesische Produkt. Typischer Anwendungsfall: Jede App auf jedem Cluster.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: all-apps-all-clusters
  namespace: argocd
spec:
  generators:
    - matrix:
        generators:
          - git:
              repoURL: https://github.com/org/k8s-apps.git
              revision: HEAD
              directories:
                - path: apps/*
          - clusters:
              selector:
                matchLabels:
                  environment: production
  template:
    metadata:
      name: '{{path.basename}}-{{name}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/k8s-apps.git
        targetRevision: HEAD
        path: '{{path}}'
      destination:
        server: '{{server}}'
        namespace: '{{path.basename}}'

Bei 5 Apps und 3 Clustern entstehen 15 Applications. Automatisch. Ohne ein einziges zusätzliches YAML.

Pull Request Generator

Der PR Generator erstellt temporäre Applications für Pull Requests. Ideal für Preview-Environments:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: pr-previews
  namespace: argocd
spec:
  generators:
    - pullRequest:
        github:
          owner: org
          repo: frontend-app
          labels:
            - preview
        requeueAfterSeconds: 60
  template:
    metadata:
      name: 'preview-{{branch_slug}}'
    spec:
      project: previews
      source:
        repoURL: https://github.com/org/frontend-app.git
        targetRevision: '{{head_sha}}'
        path: k8s/preview
        helm:
          parameters:
            - name: ingress.host
              value: '{{branch_slug}}.preview.example.com'
      destination:
        server: https://kubernetes.default.svc
        namespace: 'preview-{{number}}'
      syncPolicy:
        automated:
          prune: true
        syncOptions:
          - CreateNamespace=true

Sobald ein PR mit dem Label preview geöffnet wird, entsteht ein eigenes Deployment. Beim Merge wird es automatisch gelöscht.

Mono-Repo vs Multi-Repo

Mono-Repo funktioniert gut mit dem Directory Generator. Alle Apps in einem Repository, ein ApplicationSet erzeugt alles. Einfach, aber bei großen Teams kann es zu Merge-Konflikten kommen.

Multi-Repo erfordert den File Generator oder eine List-Generator-Konfiguration, die auf verschiedene Repositories verweist. Mehr Aufwand beim Setup, aber Teams arbeiten unabhängig.

In der Praxis bewährt sich ein Hybrid: App-Code in separaten Repos, Kubernetes-Manifeste in einem zentralen Config-Repo. Das Config-Repo nutzt den Directory Generator.

Best Practices

Sync Policies bewusst wählen. Automated Sync mit selfHeal: true und prune: true ist mächtig — aber auch gefährlich. Für Production empfiehlt sich automated ohne prune oder manueller Sync mit Approval.

Labels für Cluster-Selektion. Nutze Labels wie environment, region und tier statt Cluster-Namen. Das entkoppelt die ApplicationSet-Definition von der konkreten Infrastruktur.

Progressive Rollouts. Kombiniere den Matrix Generator mit unterschiedlichen targetRevisions pro Umgebung. Staging zeigt auf HEAD, Production auf einen Git-Tag.

FAQ

Brauche ich ApplicationSets, wenn ich nur 3-4 Apps habe?

Bei wenigen Apps reichen einzelne Application-Manifeste. ApplicationSets lohnen sich ab etwa 10 Apps oder bei Multi-Cluster-Setups, wo Wiederholung zur Fehlerquelle wird.

Kann ein ApplicationSet Applications in mehreren ArgoCD-Projekten erstellen?

Nein, das Template hat ein festes project-Feld. Für verschiedene Projekte brauchst du separate ApplicationSets. Du kannst aber den Projektnamen über Generator-Parameter dynamisch setzen.

Was passiert, wenn ein Generator-Ergebnis verschwindet?

Wenn ein Verzeichnis gelöscht wird oder ein Cluster-Label entfernt wird, löscht das ApplicationSet die zugehörige Application. Mit preserveResourcesOnDeletion: true im Template bleiben die Kubernetes-Ressourcen im Cluster erhalten.

Wie debugge ich ApplicationSet-Probleme?

Prüfe den ApplicationSet-Controller: kubectl logs -n argocd deployment/argocd-applicationset-controller. Häufige Fehler sind falsche Pfade im Git Generator oder fehlende Cluster-Labels.

Funktionieren ApplicationSets auch mit Helm Charts?

Ja. Im Template-Source-Abschnitt kannst du helm statt path verwenden und Helm-spezifische Parameter über Generator-Variablen setzen — wie im File-Generator-Beispiel oben gezeigt.

Nächster Schritt: Starte mit dem Directory Generator für ein Mono-Repo oder dem Cluster Generator für Multi-Cluster-Infrastruktur. Für die sichere Verwaltung von Secrets in deinem GitOps-Workflow lies unseren GitOps Secrets Guide.