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