Understanding ApplicationSets - Generators (Part 2)

July 17, 2026
Gerald Nunn
Related topics:
GitOps
Related products:
Red Hat OpenShift GitOps

Introduction

In Part 1 of this series we had a very brief introduction to ApplicationSet Generators but more importantly reviewed how to view the underlying parameters that Generators create and pass on to the template when creating Applications. 

In this second part of the series, we will use this technique to do a deeper dive on how the Generators work as well as dig into some of the more useful generators.

Generator Definitions

The first thing to note when looking at the ApplicationSet.spec.generators is that it is an array of Objects:

$ kubectl explain ApplicationSet.spec.generators
KIND:     ApplicationSet
VERSION:  argoproj.io/v1alpha1
RESOURCE: generators <[]Object>
DESCRIPTION:
     <empty>
FIELDS:

   clusterDecisionResource      <Object>

   clusters     <Object>

   git  <Object>

   list <Object>

   matrix       <Object>

   merge        <Object>

   plugin       <Object>

   pullRequest  <Object>

   scmProvider  <Object>

   selector     <Object>

When starting with ApplicationSets one of the first questions might be “How does this work if I define multiple generators?”, and rest assured one that will be answered later in this blog.

For now note that the above command shows us the different generators that are available in ApplicationSets so let’s review some of the more commonly used generators. Note the intent of this blog isn’t to comprehensively cover every generator, the documentation does a fine job of that but rather highlight some of the features and quirks.

List Generator

The List generator is a basic generator that provides a good entry point for someone new to ApplicationSets. As we saw in Part 1, the List Generator enables specifying a static list of elements in an array. Since it is static when used on its own it tends to be most used when the elements are known beforehand and not likely to change much over time.

As a standalone generator it is not particularly useful in the author’s opinion compared to using a Helm chart to generate the App-of-App pattern. It becomes much more useful when combined with other generators as will be shown later.

Cluster Generator

The Cluster generator returns the list of the clusters configured in Argo CD along with the metadata, labels and annotations on those cluster Secrets. Specific clusters can be selected either by using a label selector or based on the Kubernetes version.

The ability to provide additional context with labels and annotations on the cluster Secret is incredibly useful. As an example, OpenShift clusters have some important per-cluster information that is required when configuring the clusters such as the infrastructure_id for the Machine API or the API and Wildcard hosts when configuring TLS certificates.

Adding this information to the cluster Secret enables passing this information to the templated Applications, either as Helm parameters or as Kustomize patches, to minimize the amount of bespoke cluster configuration that becomes burdensome when dealing with hundreds or thousands of clusters.

Note: A GitOps purist may argue that you should avoid having Helm parameters or Kustomize patches in the Applications since it splits the information needed to build the manifests in two places. While I do generally agree that it should be avoided, in cases such as this I freely admit that I tend towards pragmatism.

Finally note that by default the local cluster, in-cluster, will not have a Secret defined for it and therefore no ability to contribute additional metadata. If this additional metadata is needed, simply create a Secret for the local cluster which can be named either in-cluster or given an alternative name if there is a cluster-naming convention in use.

Note: The author recommends using a cluster naming convention when managing large fleets of clusters, ideally a naming scheme that conveys some information about the clusters. Checkout the author’s current OpenShift cluster configuration, cluster-config-v2, repository for one possible scheme.

Automation should be used to manage the cluster Secrets when working with large numbers of clusters. This automation provides an excellent opportunity to provide additional context as labels and annotations to the Cluster Secret. Red Hat Advanced Cluster Manager provides tooling to manage these Secrets with the GitOpsCluster Custom Resource as an example. 

Important: As a recommended practice, use labels for selectable information and annotations for contextual information. Also note that labels in Kubernetes are limited to 63 characters.

Finally the cluster generator supports specifying additional values. While the documentation shows adding static key value pairs you can reference the generator parameters for the current instance. It also supports using any functions that are supported in the Go Templates in ApplicationSets for more complex situations. 

Here is an example snippet of using the ternary function to indicate whether the cluster secret is referencing an Argo CD Agent based on the presence of a label. 

generators:
  - clusters:
      selector:
        matchLabels:
          app.kubernetes.io/name: "hub-prod-local"
          argocd.argoproj.io/secret-type: cluster
      values:
        argoCDAgent: '{{ ternary "true" "false" (ne (index .metadata.labels "argocd-agent.argoproj-labs.io/agent-name") "") }}'

Git Generator

When using GitOps it's a bit of a given that the Git Generator is incredibly useful. It generates Applications based on the contents of a git repository and supports two modes of operation:

  • directories - generates Applications based on matching directories in the repository
  • files - generates Applications based on matching files, the matching file can contain additional parameters which the generator will pass to the template. The file can be either a JSON or a YAML file.

The directories mode is useful for either simple cases or where the Applications that are generated are uniform in nature. For example, generating environment (dev/stage/prod) specific Applications for a common deployable tends to work well with the directories mode since they share the same characteristics and common base.

The challenge with the directories mode is when you need to deal with exceptions. For example this Application needs Server-Side Apply, this Application requires a specific SyncOption, this Application needs an ignoreDifferences stanza, etc. Even though the files mode is somewhat more complex to maintain, since you need to create an additional file in the repository for every match, the ability to specify additional parameters is invaluable when working with exceptions.

A use case where files mode is particularly useful is when using an ApplicationSet to generate Applications for cluster configuration. In this context an ApplicationSet would be deploying a set of disparate applications (cert-manager, External Secrets Operator, Kyverno, etc) and one or more of those may require specific configuration in the Application to deploy correctly.

Note: Readers might be wondering, why not split the ApplicationSet into the specific domains, i.e. one ApplicationSet just for cert-manager, one for External Secrets Operator, etc. The challenge with this is when bootstrapping a cluster you need to deploy things in a specific order, i.e. cert-manager needs to be deployed before anything can request certificates. In Argo CD it is not possible to orchestrate this ordering across multiple ApplicationSets. 

Using a tweaked example from the Git Generator documentation for files mode, let’s have a look at the parameters being generated:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
  - git:
      repoURL: https://github.com/argoproj/argo-cd.git
      revision: HEAD
      files:
      - path: "applicationset/examples/git-generator-files-discovery/cluster-config/**/config.json"
      values:
        repoURL: https://github.com/argoproj/argo-cd.git
        revision: HEAD
  template:
    metadata:
      name: '{{.cluster.name}}-guestbook'
    spec:
      info:
        - name: "parameters"
          value: |
            {{ toPrettyJson . }}
      project: default
      source:
        repoURL: "{{.values.repoURL}}"
        targetRevision: "{{.values.revision}}"
        path: "applicationset/examples/git-generator-files-discovery/apps/guestbook"
      destination:
        server: '{{.cluster.address}}'
        namespace: guestbook

In this example, any matches to the config.json file in the applicationset/examples/git-generator-files-discovery/cluster-config/** glob pattern would be a match. 

Run the command to generate the Applications and collect the parameters: 

argocd appset generate appset_git_file_generator.yaml -o json | jq '[.[].spec.info.[].value | fromjson]'

This is the output that will be generated:

[
  {
    "asset_id": "11223344",
    "aws_account": "123456",
    "cluster": {
      "address": "http://1.2.3.4",
      "name": "engineering-dev",
      "owner": "cluster-admin@company.com"
    },
    "path": {
      "basename": "dev",
      "basenameNormalized": "dev",
      "filename": "config.json",
      "filenameNormalized": "config.json",
      "path": "applicationset/examples/git-generator-files-discovery/cluster-config/engineering/dev",
      "segments": [
        "applicationset",
        "examples",
        "git-generator-files-discovery",
        "cluster-config",
        "engineering",
        "dev"
      ]
    },
    "values": {
      "repoURL": "https://github.com/argoproj/argo-cd.git",
      "revision": "HEAD"
    }
  },
  {
    "asset_id": "11223344",
    "aws_account": "123456",
    "cluster": {
      "address": "http://1.2.3.4",
      "name": "engineering-prod",
      "owner": "cluster-admin@company.com"
    },
    "path": {
      "basename": "prod",
      "basenameNormalized": "prod",
      "filename": "config.json",
      "filenameNormalized": "config.json",
      "path": "applicationset/examples/git-generator-files-discovery/cluster-config/engineering/prod",
      "segments": [
        "applicationset",
        "examples",
        "git-generator-files-discovery",
        "cluster-config",
        "engineering",
        "prod"
      ]
    },
    "values": {
      "repoURL": "https://github.com/argoproj/argo-cd.git",
      "revision": "HEAD"
    }
  }
]

Notice in the parameters the git generator did not include the repoURL or the revision which is unfortunate for a couple of reasons. First it would be good to reference these as variables in the template to keep things DRY, second if using multiple git generators the repoURL and revision will be needed in the templated Application. 

Note: There is a open issue for this in Argo CD.

As we did here, if you require this information as a parameter, include it in the values since like the Cluster generator the Git generator supports passing additional parameters.  While not perfectly DRY, it keeps the information close to where it originated making it less likely to be missed if there is an update to either.

Also note in the above there are the expected parameters from the Git generator under .path but notice we have a bunch of new parameters .asset_id, .aws_account and .cluster. These are all sourced from the config.json which was matched by the glob pattern:

{
  "aws_account": "123456",
  "asset_id": "11223344",
  "cluster": {
    "owner": "cluster-admin@company.com",
    "name": "engineering-dev",
    "address": "http://1.2.3.4"
  }
}

Important: While this example uses JSON the Git files generator can also use YAML files, the author prefers YAML to maintain consistency with manifests plus it has less verbosity. However feel free to choose the format that works best for you.

Using Multiple Generators

As mentioned previously, ApplicationSets support defining multiple generates, so what happens if we do just that? Here is an example of combining the list and cluster generators into a single ApplicationSet:

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://kubernetes.default.svc
      - cluster: engineering-prod
        url: https://kubernetes.default.svc
  - clusters: {}
  template:
    metadata:
      name: 'guestbook'
    spec:
      info:
        - name: "parameters"
          value: |
            {{ toPrettyJson . }}
      project: "default"
      source:
        repoURL: https://github.com/argoproj/argo-cd.git
        targetRevision: HEAD
        path: applicationset/examples/list-generator/guestbook
      destination:
        server: 'https://kubernetes.default.svc'
        namespace: guestbook

Run this command to generate the parameters:

argocd appset generate appset_two_generators.yaml -o json | jq '[.[].spec.info.[].value | fromjson]'

The following is the output that is generated however note that since the cluster generator is dynamic your result will vary:

[
  {
    "cluster": "engineering-dev",
    "url": "https://kubernetes.default.svc"
  },
  {
    "cluster": "engineering-prod",
    "url": "https://kubernetes.default.svc"
  },
  {
    "metadata": {
      "annotations": {
        "baseDomain": "hub.ocplab.com",
        "clusterID": "1800df5d-06d8-4eea-bef8-e7f9ec791610",
        "infrastructureID": "hub-zcvzl",
        "subdomain": "apps.hub.ocplab.com",
        "targetRevision": "v1.2.1"
      },
      "labels": {
        "app.kubernetes.io/name": "hub-prod-local",
        "argocd.argoproj.io/secret-type": "cluster",
        "env": "prod",
        "region": "local",
        "type": "hub"
      }
    },
    "name": "hub-prod-local",
    "nameNormalized": "hub-prod-local",
    "project": "",
    "server": "https://kubernetes.default.svc"
  },
  {
    "metadata": {
      "annotations": {
        "argocd.argoproj.io/skip-reconcile": "true",
        "baseDomain": "home.ocplab.com",
        "clusterID": "fef08928-3f49-4dcb-8a70-ea2da63dcd2b",
        "infrastructureID": "home-ncb8t",
        "subdomain": "apps.home.ocplab.com",
        "targetRevision": "v1.2.1"
      },
      "labels": {
        "app.kubernetes.io/name": "workload-prod-local",
        "argocd-agent.argoproj-labs.io/agent-name": "workload-prod-local",
        "argocd.argoproj.io/secret-type": "cluster",
        "env": "prod",
        "region": "local",
        "type": "workload"
      }
    },
    "name": "workload-prod-local",
    "nameNormalized": "workload-prod-local",
    "project": "",
    "server": "https://argocd-agent-principal-resource-proxy.argocd.svc.cluster.local:9090?agentName=workload-prod-local"
  }
]

Examining the output above we can see that the List generator provided its parameters first while the second Cluster generator provided a completely different set of parameters second. Therefore using multiple different Generators in sequence is not particularly useful since templating this would be challenging. However where this really shines is when using the Matrix and Merge generators.

Matrix Generator

The Matrix Generator combines the parameters of two child generators into a single matrix of parameters. The documentation does an excellent job of walking through some common basic examples so let’s look at a real world scenario of managing cluster configuration.

In this example we have an individual per-cluster ApplicationSet that uses the Matrix generator to combine the Git generator with the Cluster generator. The Git generator is responsible for contributing the individual Applications (external-secrets, cert-manager, etc) while the Cluster generator selects a single cluster, hub-prod-local, and contributes cluster specific information and metadata that can be passed to the templated Applications.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: hub-prod-local
  labels:
    cluster-name: hub-prod-local
spec:
  …
  generators:
    - matrix:
        generators:
          - git:
              repoURL: https://github.com/gnunn-gitops/cluster-config-v2
              revision: main
              files:
                - path: apps/**/**/overlays/all/app-config.yaml
                - path: apps/**/**/overlays/hub/app-config.yaml
                - path: apps/**/**/overlays/hub-prod/app-config.yaml
                - path: apps/**/**/overlays/hub-prod-local/app-config.yaml
              values:
                appName: '{{ ternary (index . "appName") (index .path.segments 2) (hasKey . "appName") }}'
                grouping: '{{ index .path.segments 1 }}'
                destinationNamespace: '{{ ternary (index . "namespace") (index .path.segments 2) (hasKey . "namespace") }}'
          - clusters:
              selector:
                matchLabels:
                  app.kubernetes.io/name: "hub-prod-local"
                  argocd.argoproj.io/secret-type: cluster
              values:
                argoCDAgent: '{{ ternary "true" "false" (ne (index .metadata.labels "argocd-agent.argoproj-labs.io/agent-name") "") }}'
…

This ApplicationSet is quite complex so it has been trimmed down to just the generators which will be the focus here. The source of the complete ApplicationSet, which is generated by a Helm chart, is available in the appsets repository.

Note: This ApplicationSet is extracted from the cluster-config-v2 repository where it is used as part of a system to manage cluster configuration. If readers are interested in having a more detailed look at one possible way to manage Kubernetes/OpenShift configuration with Argo CD feel free to check it out.

Generate the ApplicationSet with parameters:

argocd appset generate appset_matrix.yaml -o json | jq '[.[].spec.info.[].value | fromjson]'

This ApplicationSet generates about thirty Applications, for brevity let’s focus on the parameters for the first Application:

[
  {
    "metadata": {                                                (1)
      "annotations": {
        "baseDomain": "hub.ocplab.com",
        "clusterID": "1800df5d-06d8-4eea-bef8-e7f9ec791610",
        "infrastructureID": "hub-zcvzl",
        "subdomain": "apps.hub.ocplab.com",
        "targetRevision": "HEAD"
      },
      "labels": {
        "app.kubernetes.io/name": "hub-prod-local",
        "argocd.argoproj.io/secret-type": "cluster",
        "env": "prod",
        "region": "local",
        "type": "hub"
      }
    },
    "name": "hub-prod-local",
    "nameNormalized": "hub-prod-local",
    "path": {                                                    (2)
      "basename": "all",
      "basenameNormalized": "all",
      "filename": "app-config.yaml",
      "filenameNormalized": "app-config.yaml",
      "path": "apps/00-core/cert-manager-operator/overlays/all",
      "segments": [
        "apps",
        "00-core",
        "cert-manager-operator",
        "overlays",
        "all"
      ]
    },
    "project": "",
    "server": "https://kubernetes.default.svc",
    "values": {
      "appName": "cert-manager-operator",
      "argoCDAgent": "false",
      "destinationNamespace": "cert-manager-operator",
      "grouping": "00-core"
    }
  },
…


 Here we see the following parameters provided:

  1. Cluster metadata including the labels, annotations and names. Notice the annotations contribute cluster-specific information (clusterID, infrastructureID, etc) that can be consumed by generated Applications as either Helm parameters or as Kustomize patches.
  2. The Git generator provides information about the file including the path segments which are used to name the Application, cert-manager-operator, as well as group it for ProgressiveSync, 00-core. Additionally while not shown here the file generator can contribute other parameters as needed to deal with exceptions or overrides.

Merge Generator

The Merge generator consumes multiple generators, it takes a base, i.e. the first, generator and then merges it with subsequent generators based on configured merge keys. While it sounds simple the author freely admits that this generator is the one that causes his brain to hurt the most when using it reality. 

This is because it is also a somewhat finicky generator, to understand why let's have a look at this simple example of modifying the number of replicas based on whether a cluster is labelled prod or dev by merging the Cluster generator with a List generator:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: merge-generator-example
  namespace: argocd
spec:
  goTemplate: false
  generators:
    - merge:
        mergeKeys:
          - values.env
        generators:
          - clusters:
              selector:
                matchLabels:
                  type: "workload"
              values:
                env: "{{metadata.labels.env}}"
                replicas: "1"
          - list:
              elements:
                - values:
                    env: dev
                    replicas: "1"
                - values:
                    env: prod
                    replicas: "3"
  template:
    metadata:
      name: "app-{{values.env}}"
    spec:
      project: default
      source:
        repoURL: https://github.com
        targetRevision: HEAD
        path: guestbook
        helm:
          parameters:
            - name: replicaCount
              value: "{{values.replicas}}"
      destination:
        server: "{{server}}"
        namespace: default

As promised, looks simple right? However the first thing to note is that this example does not use Go Templates because the Merge generator has a restriction where nested keys, i.e. values.env, cannot be used with Go Templates. The second issue is the specified merge keys must be unique, if there were multiple clusters with the prod label the following error would occur:

unable to generate Applications of ApplicationSet: error generating applications: error getting param sets by merge key: the parameters from a generator were not unique by the given mergeKeys, Merge requires all param sets to be unique. Duplicate key was {\"values.env\":\"prod\"}

Both of these issues can be circumvented by combining a Matrix generator with the Merge generator as shown below in appset_merge.yaml:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: merge-generator-example
  namespace: argocd
spec:
  goTemplate: true
  goTemplateOptions: ["missingkey=error"]
  generators:
    - matrix:
        generators:
          - clusters:
              selector:
                matchLabels:
                  type: "workload"
          - merge:
              mergeKeys:
                - env
              generators:
                # Promote the cluster env label to a top-level merge key,
                # with a default replica count.
                - list:
                    elements:
                      - env: '{{ index .metadata.labels "env" }}'
                        values:
                          replicas: "1"
                # Override replicas by environment
                - list:
                    elements:
                      - env: dev
                        values:
                          replicas: "1"
                      - env: prod
                        values:
                          replicas: "3"
  template:
    metadata:
      name: '{{ .name }}-app'
    spec:
      info:
        - name: "parameters"
          value: |
            {{ toPrettyJson . }}
      project: default
      source:
        repoURL: https://github.com
        targetRevision: HEAD
        path: guestbook
        helm:
          parameters:
            - name: replicaCount
              value: '{{ .values.replicas }}'
      destination:
        server: '{{ .server }}'
        namespace: default

Here we are using the Matrix generator to combine parameters with the Cluster generator and a Merge generator. The Merge generator has two List generators, the first accepts the parameters from the cluster generator and promotes the env parameter to the top-level which addresses the nested merge keys restriction.

Also note that the parameter set from the Cluster generator for each individual cluster is combined with the Merge generator, as a result the Merge generator only operates on one cluster at a time. Therefore it eliminates the issue of having multiple clusters labelled as prod since each merge key is unique by definition as it only appears once, per-cluster. This works because generators are executed just-in-time, they are not executed in parallel with the results then combined after the fact.

To view the parameters, execute the following:

argocd appset generate appset_merge.yaml -o json | jq '[.[].spec.info.[].value | fromjson]'

The generated parameters appear below, note the new env parameter that was added at the top level and the values.replicas being set to 3 by the Merge generator as it matches the prod label.

[
 {
    "env": "prod",
    "metadata": {
      "annotations": {
        "argocd.argoproj.io/skip-reconcile": "true",
        "baseDomain": "home.ocplab.com",
        "clusterID": "fef08928-3f49-4dcb-8a70-ea2da63dcd2b",
        "infrastructureID": "home-ncb8t",
        "subdomain": "apps.home.ocplab.com",
        "targetRevision": "HEAD"
      },
      "labels": {
        "app.kubernetes.io/name": "workload-prod-local",
        "argocd-agent.argoproj-labs.io/agent-name": "workload-prod-local",
        "argocd.argoproj.io/secret-type": "cluster",
        "env": "prod",
        "region": "local",
        "type": "workload"
      }
    },
    "name": "workload-prod-local",
    "nameNormalized": "workload-prod-local",
    "project": "",
    "server": "https://argocd-agent-principal-resource-proxy.argocd.svc.cluster.local:9090?agentName=workload-prod-local",
    "values": {
      "replicas": "3"
    }
  }
]

Conclusion

In this blog we reviewed ApplicationSet Generators with a detailed look at some of the more commonly used ones. We also reviewed how to use the Merge and Matrix generators to combine multiple generators to facilitate more complex use cases.

Disclaimer: Please note the content in this blog post has not been thoroughly reviewed by the Red Hat Developer editorial team. Any opinions expressed in this post are the author's own and do not necessarily reflect the policies or positions of Red Hat.