Templates

The template fields of the ApplicationSet spec are used to generate Argo CD Application resources.

Template fields

An Argo CD Application is created by combining the parameters from the generator with fields of the template (via {{values}}), and from that a concrete Application resource is produced and applied to the cluster.

Here is the template subfield from a Cluster generator:

  1. # (...)
  2.  template:
  3.    metadata:
  4.      name: '{{cluster}}-guestbook'
  5.    spec:
  6.      source:
  7.        repoURL: https://github.com/infra-team/cluster-deployments.git
  8.        targetRevision: HEAD
  9.        path: guestbook/{{cluster}}
  10.      destination:
  11.        server: '{{url}}'
  12.        namespace: guestbook

The template subfields correspond directly to the spec of an Argo CD Application resource:

  • project refers to the Argo CD Project in use (default may be used here to utilize the default Argo CD Project)
  • source defines from which Git repository to extract the desired Application manifests
    • repoURL: URL of the repository (eg https://github.com/argoproj/argocd-example-apps.git)
    • targetRevision: Revision (tag/branch/commit) of the repository (eg HEAD)
    • path: Path within the repository where Kubernetes manifests (and/or Helm, Kustomize, Jsonnet resources) are located
  • destination: Defines which Kubernetes cluster/namespace to deploy to
    • name: Name of the cluster (within Argo CD) to deploy to
    • server: API Server URL for the cluster (Example: https://kubernetes.default.svc)
    • namespace: Target namespace in which to deploy the manifests from source (Example: my-app-namespace)

Note:

  • Referenced clusters must already be defined in Argo CD, for the ApplicationSet controller to use them
  • Only one of name or server may be specified: if both are specified, an error is returned.

The metadata field of template may also be used to set an Application name, or to add labels or annotations to the Application.

While the ApplicationSet spec provides a basic form of templating, it is not intended to replace the full-fledged configuration management capabilities of tools such as Kustomize, Helm, or Jsonnet.

Deploying ApplicationSet resources as part of a Helm chart

ApplicationSet uses the same templating notation as Helm ({{}}). If the ApplicationSet templates aren’t written as Helm string literals, Helm will throw an error like function "cluster" not defined. To avoid that error, write the template as a Helm string literal. For example:

  1.     metadata:
  2.       name: '{{`{{cluster}}`}}-guestbook'

This only applies if you use Helm to deploy your ApplicationSet resources.

Generator templates

In addition to specifying a template within the .spec.template of the ApplicationSet resource, templates may also be specified within generators. This is useful for overriding the values of the spec-level template.

The generator’s template field takes precedence over the spec‘s template fields:

  • If both templates contain the same field, the generator’s field value will be used.
  • If only one of those templates’ fields has a value, that value will be used.

Generator templates can thus be thought of as patches against the outer spec-level template fields.

  1. apiVersion: argoproj.io/v1alpha1
  2. kind: ApplicationSet
  3. metadata:
  4.   name: guestbook
  5. spec:
  6.   generators:
  7.   - list:
  8.       elements:
  9.         - cluster: engineering-dev
  10.           url: https://kubernetes.default.svc
  11.       template:
  12.         metadata: {}
  13.         spec:
  14.           project: "default"
  15.           source:
  16.             revision: HEAD
  17.             repoURL: https://github.com/argoproj/argo-cd.git
  18.             # New path value is generated here:
  19.             path: 'applicationset/examples/template-override/{{cluster}}-override'
  20.           destination: {}
  22.   template:
  23.     metadata:
  24.       name: '{{cluster}}-guestbook'
  25.     spec:
  26.       project: "default"
  27.       source:
  28.         repoURL: https://github.com/argoproj/argo-cd.git
  29.         targetRevision: HEAD
  30.         # This 'default' value is not used: it is is replaced by the generator's template path, above
  31.         path: applicationset/examples/template-override/default
  32.       destination:
  33.         server: '{{url}}'
  34.         namespace: guestbook

(The full example can be found here.)

In this example, the ApplicationSet controller will generate an Application resource using the path generated by the List generator, rather than the path value defined in .spec.template.