Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท Multi-cluster and ApplicationSets

ApplicationSet Generators: List, Cluster and Git

Generate many Applications from one template with ApplicationSet: list, cluster, Git directory and file generators, templating and a runnable model.

Writing one Application per service per cluster does not scale. If you have 40 services and 6 clusters, that is 240 manifests that differ in a few values. An ApplicationSet is a separate resource, handled by the ApplicationSet controller, that produces Applications from a template and a list of parameter sets supplied by generators.

flowchart LR
  G["Generator"] --> P["Parameter sets"]
  T["Template"] --> X["Render each set"]
  P --> X
  X --> A["Applications"]

Generators produce parameters; the template turns each set into an Application.

The smallest ApplicationSet

YAML
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
    - list:
        elements:
          - env: staging
            replicas: "1"
          - env: prod
            replicas: "5"
  template:
    metadata:
      name: "guestbook-{{ .env }}"
    spec:
      project: default
      source:
        repoURL: https://git.example.com/platform/gitops.git
        targetRevision: main
        path: "guestbook/overlays/{{ .env }}"
      destination:
        name: in-cluster
        namespace: "guestbook-{{ .env }}"

Two Applications, guestbook-staging and guestbook-prod, come out. Edit or delete an element and the controller creates, updates or deletes Applications to match.

goTemplate: true selects Go templates ({{ .env }}) with Sprig functions. The older default, fasttemplate ({{env}}), is simpler but has no conditionals; prefer Go templates in new work, with missingkey=error so typos fail loudly instead of rendering empty strings.

List generator

An inline list of maps. Good for a handful of fixed targets. Each element's keys become template parameters.

Cluster generator

Produces one parameter set per cluster registered in Argo CD, optionally filtered by labels:

YAML
generators:
  - clusters:
      selector:
        matchLabels:
          env: prod
      values:
        tier: critical

Available parameters: name, server, metadata.labels.<key>, metadata.annotations.<key>, and anything under values. Register a new cluster with the right labels and its Applications appear with no further edits. Use this to install platform add-ons (ingress, monitoring) on every cluster.

YAML
template:
  metadata:
    name: "ingress-{{ .name }}"
  spec:
    destination:
      server: "{{ .server }}"
      namespace: ingress

Git directory generator

One Application per folder in a repository:

YAML
generators:
  - git:
      repoURL: https://git.example.com/platform/gitops.git
      revision: main
      directories:
        - path: apps/*
        - path: apps/experimental
          exclude: true

Parameters: path.path (apps/billing), path.basename (billing), path.basenameNormalized (a DNS-safe form), and path[0], path[1] for segments. Add a folder and an Application appears. This is the most popular pattern for monorepos: a folder is a deployable unit.

Git file generator

Reads JSON or YAML files and turns the contents into parameters:

YAML
generators:
  - git:
      repoURL: https://git.example.com/platform/gitops.git
      revision: main
      files:
        - path: "tenants/**/config.json"

A file tenants/acme/config.json containing {"tenant": "acme", "plan": "gold"} yields the parameters tenant, plan plus the path.* values. This lets product teams add an environment by committing a small config file.

Other generators

Generator Source of parameters
SCM provider Repositories in a GitHub, GitLab, Gitea or Bitbucket organization
Pull request Open pull requests, for preview environments
Cluster decision resource A custom resource filled by another controller
Plugin Any service that implements the generator plugin protocol
Matrix, Merge Combinations of other generators (see Matrix, Templates and Rollout)

Stand-in: how a generator and template interact

The runner has no Argo CD, so this stand-in implements a tiny list generator and Git directory generator and renders names with Python formatting. It is a model of the idea, not the controller.

Python Stand-in: generators plus template

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Lifecycle and safety

  • The controller owns the generated Applications and reconciles them. Manual edits are reverted.
  • If a generator returns an empty list (for example the repository is briefly unreachable and returns nothing), the controller would delete all generated Applications. Real installations protect against this with syncPolicy.preserveResourcesOnDeletion and applicationsSync: create-only or create-update, and by pinning generators to stable revisions.
  • Template names must be unique and DNS-safe. Use basenameNormalized for folder names that might contain underscores or capitals.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does an ApplicationSet produce?

    The ApplicationSet controller creates, updates and deletes Application resources.
  2. 2. Which generator makes one Application per registered cluster?

    The cluster generator iterates over the clusters registered in Argo CD, optionally filtered by labels.
  3. 3. In a Git directory generator, which parameter holds the last folder name?

    path.path is the whole path and path.basename the last segment.
  4. 4. Why use goTemplateOptions missingkey=error?

    Without it, typos silently render as empty strings or <no value>.

Summary

  • An ApplicationSet = generators + template; the controller reconciles the generated Applications.
  • List, cluster, Git directory and Git file generators cover most needs; SCM, pull request and plugin generators extend them.
  • Use Go templates with missingkey=error.
  • Protect against empty generator results with sync policy options.

Next: Matrix, Templates and Rollout