Argo CD ApplicationSet Controller

You can define a template field directly within a generator to override values in the global .spec.template. Generator templates act as patches against the outer template fields.

Precedence Rules:

• If both the generator template and the spec.template contain the same field, the generator's value takes precedence.
• If only one template contains a specific field, that value is used.

This allows you to define a common baseline in .spec.template and provide specific overrides for individual elements in a generator (e.g., a list or cluster generator).

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
spec:
  generators:
  - list:
      elements:
        - cluster: engineering-dev
          url: https://kubernetes.default.svc
      template:
        spec:
          source:
            # This path overrides the one in spec.template
            path: 'examples/template-override/{{cluster}}-override'
  template:
    spec:
      source:
        path: examples/template-override/default

The Cluster generator identifies clusters registered with Argo CD (stored as Secrets in the Argo CD namespace) and produces parameters to target them. For every cluster secret found, it provides the following parameters to the Application template:

• name: The name of the cluster from the Secret.
• nameNormalized: The cluster name converted to lowercase alphanumeric characters, -, or . (useful for creating valid Kubernetes resource names).
• server: The cluster server URL from the Secret.
• metadata.labels.<key>: Any label present in the Secret's metadata.
• metadata.annotations.<key>: Any annotation present in the Secret's metadata.

This allows you to dynamically generate Applications that target specific clusters using their metadata.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook
  namespace: argocd
spec:
  generators:
  - clusters: {}
  template:
    metadata:
      name: '{{nameNormalized}}-guestbook'
    spec:
      project: "default"
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps/
        targetRevision: HEAD
        path: guestbook
      destination:
        server: '{{server}}'
        namespace: guestbook

The clusterDecisionResource generator allows an ApplicationSet to dynamically generate applications based on the status of a custom Kubernetes resource.

Mechanism

1. Resource Scanning: The generator reads a specific resource's status field to find a list of clusters.
2. Duck Typing: The generator looks for a list of key/value pairs where the values match existing ArgoCD cluster names.
3. Parameter Availability: For every element in the identified list, all key/value pairs within that element are injected into the ApplicationSet template. Additionally, the standard name and server parameters remain available.
4. Configuration: You must use a ConfigMap to tell the generator which resource to watch and how to parse its status.

Configuration via ConfigMap

To use this generator, create a ConfigMap in the ArgoCD namespace with the following data keys:

• apiVersion: The apiVersion of the resource to be read.
• kind: The plural kind of the resource.
• statusListKey: The key within the resource's status that contains the list of clusters (defaults to clusters).
• matchKey: The key name used within the list elements to identify the cluster name (e.g., name or clusterName).

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-configmap
data:
  apiVersion: group.io/v1
  kind: mykinds
  statusListKey: clusters
  matchKey: name

An ApplicationSet uses a spec.template to define the structure of the Argo CD Application resources it produces. The controller combines parameters provided by a generator with the fields defined in the template using {{values}} syntax to create concrete Application resources.

Key template fields correspond to the Argo CD Application spec:

• project: The Argo CD Project to use (e.g., default).
• source:
  • repoURL: URL of the Git repository.
  • targetRevision: Revision (tag, branch, or commit) of the repository.
  • path: Path within the repository where manifests are located.
• destination:
  • name: Name of the cluster (as defined in Argo CD).
  • server: API Server URL for the cluster.
  • namespace: Target namespace for deployment.

Important Constraints:

• Referenced clusters must already be defined in Argo CD.
• In the destination field, you must specify either name or server, but not both. Specifying both will result in an error.

# Example template subfield from a Cluster generator
template:
  metadata:
    name: '{{cluster}}-guestbook'
  spec:
    source:
      repoURL: https://github.com/infra-team/cluster-deployments.git
      targetRevision: HEAD
      path: guestbook/{{cluster}}
    destination:
      server: '{{url}}'
      namespace: guestbook

The clusterDecisionResource generator uses duck-typing to extract cluster information from a Kubernetes resource's status block without needing to know the resource's full API schema.

The Duck-Typing Process

1. Identification: The generator uses the GVK (Group, Version, Kind) provided in a ConfigMap to find the target resource.
2. Extraction: It looks at the status field of that resource and navigates to the key defined by statusListKey (e.g., decisions).
3. Validation: For every item in that list, it looks at the value of the key defined by matchKey (e.g., clusterName). It then checks if that value corresponds to a valid cluster name already registered in Argo CD.
4. Parameterization: Every key/value pair found inside the list items is injected into the ApplicationSet template as a parameter.

Example Resource Shape

The target resource being watched should look like this:

apiVersion: mallard.io/v1beta1
kind: Duck
metadata:
  name: quak
status:
  decisions:
  - clusterName: cluster-01
  - clusterName: cluster-02