github.com/argoproj/argo-cd/v2@v2.10.9/docs/operator-manual/applicationset/Template.md (about)

     1  # Templates
     2  
     3  The template fields of the ApplicationSet `spec` are used to generate Argo CD `Application` resources.
     4  
     5  ApplicationSet is using [fasttemplate](https://github.com/valyala/fasttemplate) but will be soon deprecated in favor of Go Template. 
     6  
     7  ## Template fields
     8  
     9  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.
    10  
    11  Here is the template subfield from a Cluster generator:
    12  ```yaml
    13  # (...)
    14   template:
    15     metadata:
    16       name: '{{cluster}}-guestbook'
    17     spec:
    18       source:
    19         repoURL: https://github.com/infra-team/cluster-deployments.git
    20         targetRevision: HEAD
    21         path: guestbook/{{cluster}}
    22       destination:
    23         server: '{{url}}'
    24         namespace: guestbook
    25  ```
    26  
    27  The template subfields correspond directly to [the spec of an Argo CD `Application` resource](../../declarative-setup/#applications):
    28  
    29  - `project` refers to the [Argo CD Project](../../user-guide/projects.md) in use (`default` may be used here to utilize the default Argo CD Project)
    30  - `source` defines from which Git repository to extract the desired Application manifests
    31      - **repoURL**: URL of the repository (eg `https://github.com/argoproj/argocd-example-apps.git`)
    32      - **targetRevision**: Revision (tag/branch/commit) of the repository (eg `HEAD`)
    33      - **path**: Path within the repository where Kubernetes manifests (and/or Helm, Kustomize, Jsonnet resources) are located
    34  - `destination`: Defines which Kubernetes cluster/namespace to deploy to
    35      - **name**: Name of the cluster (within Argo CD) to deploy to
    36      - **server**: API Server URL for the cluster (Example: `https://kubernetes.default.svc`)
    37      - **namespace**: Target namespace in which to deploy the manifests from `source` (Example: `my-app-namespace`)
    38  
    39  Note:
    40  
    41  - Referenced clusters must already be defined in Argo CD, for the ApplicationSet controller to use them
    42  - Only **one** of `name` or `server` may be specified: if both are specified, an error is returned.
    43  
    44  The `metadata` field of template may also be used to set an Application `name`, or to add labels or annotations to the Application.
    45  
    46  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.
    47  
    48  ### Deploying ApplicationSet resources as part of a Helm chart
    49  
    50  ApplicationSet uses the same templating notation as Helm (`{{}}`). If the ApplicationSet templates aren't written as
    51  Helm string literals, Helm will throw an error like `function "cluster" not defined`. To avoid that error, write the
    52  template as a Helm string literal. For example:
    53  
    54  ```yaml
    55      metadata:
    56        name: '{{`{{.cluster}}`}}-guestbook'
    57  ```
    58  
    59  This _only_ applies if you use Helm to deploy your ApplicationSet resources.
    60  
    61  ## Generator templates
    62  
    63  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.
    64  
    65  The generator's `template` field takes precedence over the `spec`'s template fields:
    66  
    67  - If both templates contain the same field, the generator's field value will be used.
    68  - If only one of those templates' fields has a value, that value will be used.
    69  
    70  Generator templates can thus be thought of as patches against the outer `spec`-level template fields.
    71  
    72  ```yaml
    73  apiVersion: argoproj.io/v1alpha1
    74  kind: ApplicationSet
    75  metadata:
    76    name: guestbook
    77  spec:
    78    generators:
    79    - list:
    80        elements:
    81          - cluster: engineering-dev
    82            url: https://kubernetes.default.svc
    83        template:
    84          metadata: {}
    85          spec:
    86            project: "default"
    87            source:
    88              revision: HEAD
    89              repoURL: https://github.com/argoproj/argo-cd.git
    90              # New path value is generated here:
    91              path: 'applicationset/examples/template-override/{{cluster}}-override'
    92            destination: {}
    93  
    94    template:
    95      metadata:
    96        name: '{{cluster}}-guestbook'
    97      spec:
    98        project: "default"
    99        source:
   100          repoURL: https://github.com/argoproj/argo-cd.git
   101          targetRevision: HEAD
   102          # This 'default' value is not used: it is is replaced by the generator's template path, above
   103          path: applicationset/examples/template-override/default
   104        destination:
   105          server: '{{url}}'
   106          namespace: guestbook
   107  ```
   108  (*The full example can be found [here](https://github.com/argoproj/argo-cd/tree/master/applicationset/examples/template-override).*)
   109  
   110  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`.
   111  
   112  ## Template Patch
   113  
   114  Templating is only available on string type. However, some use cases may require applying templating on other types.
   115  
   116  Example:
   117  
   118  - Conditionally set the automated sync policy.
   119  - Conditionally switch prune boolean to `true`.
   120  - Add multiple helm value files from a list.
   121  
   122  The `templatePatch` feature enables advanced templating, with support for `json` and `yaml`.
   123  
   124  ```yaml
   125  apiVersion: argoproj.io/v1alpha1
   126  kind: ApplicationSet
   127  metadata:
   128    name: guestbook
   129  spec:
   130    goTemplate: true
   131    generators:
   132    - list:
   133        elements:
   134          - cluster: engineering-dev
   135            url: https://kubernetes.default.svc
   136            autoSync: true
   137            prune: true
   138            valueFiles:
   139              - values.large.yaml
   140              - values.debug.yaml
   141    template:
   142      metadata:
   143        name: '{{.cluster}}-deployment'
   144      spec:
   145        project: "default"
   146        source:
   147          repoURL: https://github.com/infra-team/cluster-deployments.git
   148          targetRevision: HEAD
   149          path: guestbook/{{ .cluster }}
   150        destination:
   151          server: '{{.url}}'
   152          namespace: guestbook
   153    templatePatch: |
   154      spec:
   155        source:
   156          helm:
   157            valueFiles:
   158            {{- range $valueFile := .valueFiles }}
   159              - {{ $valueFile }}
   160            {{- end }}
   161      {{- if .autoSync }}
   162        syncPolicy:
   163          automated:
   164            prune: {{ .prune }}
   165      {{- end }}
   166  ```
   167  
   168  !!! important
   169      The `templatePatch` can apply arbitrary changes to the template. If parameters include untrustworthy user input, it 
   170      may be possible to inject malicious changes into the template. It is recommended to use `templatePatch` only with 
   171      trusted input or to carefully escape the input before using it in the template. Piping input to `toJson` should help
   172      prevent, for example, a user from successfully injecting a string with newlines.
   173  
   174      The `spec.project` field is not supported in `templatePatch`. If you need to change the project, you can use the
   175      `spec.project` field in the `template` field.
   176  
   177  !!! important
   178      When writing a `templatePatch`, you're crafting a patch. So, if the patch includes an empty `spec: # nothing in here`, it will effectively clear out existing fields. See [#17040](https://github.com/argoproj/argo-cd/issues/17040) for an example of this behavior.