github.com/migueleliasweb/helm@v2.6.1+incompatible/docs/chart_best_practices/templates.md (about)

     1  # Templates
     2  
     3  This part of the Best Practices Guide focuses on templates.
     4  
     5  ## Structure of templates/
     6  
     7  The templates directory should be structured as follows:
     8  
     9  - Template files should have the extension `.yaml` if they produce YAML output. The
    10    extension `.tpl` may be used for template files that produce no formatted content.
    11  - Template file names should use dashed notation (`my-example-configmap.yaml`), not camelcase.
    12  - Each resource definition should be in its own template file.
    13  - Template file names should reflect the resource kind in the name. e.g. `foo-pod.yaml`,
    14    `bar-svc.yaml`
    15  
    16  ## Names of Defined Templates
    17  
    18  Defined templates (templates created inside a `{{ define }} ` directive) are
    19  globally accessible. That means that a chart and all of its subcharts will have
    20  access to all of the templates created with `{{ define }}`.
    21  
    22  For that reason, _all defined template names should be namespaced._
    23  
    24  Correct:
    25  
    26  ```yaml
    27  {{- define "nginx.fullname" }}
    28  {{/* ... */}}
    29  {{ end -}}
    30  ```
    31  
    32  Incorrect:
    33  
    34  ```yaml
    35  {{- define "fullname" -}}
    36  {{/* ... */}}
    37  {{ end -}}
    38  ```
    39  
    40  ## Formatting Templates
    41  
    42  Templates should be indented using _two spaces_ (never tabs).
    43  
    44  Template directives should have whitespace after the opening  braces and before the
    45  closing braces:
    46  
    47  Correct:
    48  ```
    49  {{ .foo }}
    50  {{ print "foo" }}
    51  {{- print "bar" -}}
    52  ```
    53  
    54  Incorrect:
    55  ```
    56  {{.foo}}
    57  {{print "foo"}}
    58  {{-print "bar"-}}
    59  ```
    60  
    61  Templates should chomp whitespace where possible:
    62  
    63  ```
    64  foo:
    65    {{- range .Values.items }}
    66    {{ . }}
    67    {{ end -}}
    68  ```
    69  
    70  Blocks (such as control structures) may be indented to indicate flow of the template code.
    71  
    72  ```
    73  {{ if $foo -}}
    74    {{- with .Bar }}Hello{{ end -}}
    75  {{- end -}} 
    76  ```
    77  
    78  However, since YAML is a whitespace-oriented language, it is often not possible for code indentation to follow that convention.
    79  
    80  ## Whitespace in Generated Templates
    81  
    82  It is preferable to keep the amount of whitespace in generated templates to
    83  a minimum. In particular, numerous blank lines should not appear adjacent to each
    84  other. But occasional empty lines (particularly between logical sections) is
    85  fine.
    86  
    87  This is best:
    88  
    89  ```yaml
    90  apiVersion: batch/v1
    91  kind: Job
    92  metadata:
    93    name: example
    94    labels:
    95      first: first
    96      second: second
    97  ```
    98  
    99  This is okay:
   100  
   101  ```yaml
   102  apiVersion: batch/v1
   103  kind: Job
   104  
   105  metadata:
   106    name: example
   107  
   108    labels:
   109      first: first
   110      second: second
   111  
   112  ```
   113  
   114  But this should be avoided:
   115  
   116  ```yaml
   117  apiVersion: batch/v1
   118  kind: Job
   119  
   120  metadata:
   121    name: example
   122  
   123  
   124  
   125  
   126  
   127    labels:
   128      first: first
   129  
   130      second: second
   131  
   132  ```
   133  
   134  ## Comments (YAML Comments vs. Template Comments)
   135  
   136  Both YAML and Helm Templates have comment markers.
   137  
   138  YAML comments:
   139  ```yaml
   140  # This is a comment
   141  type: sprocket
   142  ```
   143  
   144  Template Comments:
   145  ```yaml
   146  {{- /*
   147  This is a comment.
   148  */ -}}
   149  type: frobnitz
   150  ```
   151  
   152  Template comments should be used when documenting features of a template, such as explaining a defined template:
   153  
   154  ```yaml
   155  {{- /*
   156  mychart.shortname provides a 6 char truncated version of the release name.
   157  */ }}
   158  {{ define "mychart.shortname" -}}
   159  {{ .Release.Name | trunc 6 }}
   160  {{- end -}}
   161  
   162  ```
   163  
   164  Inside of templates, YAML comments may be used when it is useful for Helm users to (possibly) see the comments during debugging.
   165  
   166  ```
   167  # This may cause problems if the value is more than 100Gi
   168  memory: {{ .Values.maxMem | quote }}
   169  ```
   170  
   171  The comment above is visible when the user runs `helm install --debug`, while
   172  comments specified in `{{- /* */ -}}` sections are not.
   173  
   174  ## Use of JSON in Templates and Template Output
   175  
   176  YAML is a superset of JSON. In some cases, using a JSON syntax can be more
   177  readable than other YAML representations.
   178  
   179  For example, this YAML is closer to the normal YAML method of expressing lists:
   180  
   181  ```yaml
   182  arguments: 
   183    - "--dirname"
   184    - "/foo"
   185  ```
   186  
   187  But it is easier to read when collapsed into a JSON list style:
   188  
   189  ```yaml
   190  arguments: ["--dirname", "/foo"]
   191  ```
   192  
   193  Using JSON for increased legibility is good. However, JSON syntax should not
   194  be used for representing more complex constructs.
   195  
   196  When dealing with pure JSON embedded inside of YAML (such as init container
   197  configuration), it is of course appropriate to use the JSON format.