github.com/koderover/helm@v2.17.0+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  It is highly recommended that new charts are created via `helm create` command as the template names are automatically defined as per this best practice.
    40  
    41  ## Formatting Templates
    42  
    43  Templates should be indented using _two spaces_ (never tabs).
    44  
    45  Template directives should have whitespace after the opening  braces and before the
    46  closing braces:
    47  
    48  Correct:
    49  ```
    50  {{ .foo }}
    51  {{ print "foo" }}
    52  {{- print "bar" -}}
    53  ```
    54  
    55  Incorrect:
    56  ```
    57  {{.foo}}
    58  {{print "foo"}}
    59  {{-print "bar"-}}
    60  ```
    61  
    62  Templates should chomp whitespace where possible:
    63  
    64  ```
    65  foo:
    66    {{- range .Values.items }}
    67    {{ . }}
    68    {{ end -}}
    69  ```
    70  
    71  Blocks (such as control structures) may be indented to indicate flow of the template code.
    72  
    73  ```
    74  {{ if $foo -}}
    75    {{- with .Bar }}Hello{{ end -}}
    76  {{- end -}} 
    77  ```
    78  
    79  However, since YAML is a whitespace-oriented language, it is often not possible for code indentation to follow that convention.
    80  
    81  ## Whitespace in Generated Templates
    82  
    83  It is preferable to keep the amount of whitespace in generated templates to
    84  a minimum. In particular, numerous blank lines should not appear adjacent to each
    85  other. But occasional empty lines (particularly between logical sections) is
    86  fine.
    87  
    88  This is best:
    89  
    90  ```yaml
    91  apiVersion: batch/v1
    92  kind: Job
    93  metadata:
    94    name: example
    95    labels:
    96      first: first
    97      second: second
    98  ```
    99  
   100  This is okay:
   101  
   102  ```yaml
   103  apiVersion: batch/v1
   104  kind: Job
   105  
   106  metadata:
   107    name: example
   108  
   109    labels:
   110      first: first
   111      second: second
   112  
   113  ```
   114  
   115  But this should be avoided:
   116  
   117  ```yaml
   118  apiVersion: batch/v1
   119  kind: Job
   120  
   121  metadata:
   122    name: example
   123  
   124  
   125  
   126  
   127  
   128    labels:
   129      first: first
   130  
   131      second: second
   132  
   133  ```
   134  
   135  ## Resource Naming in Templates
   136  
   137  Hard-coding the `name:` into a resource is usually considered to be bad practice.
   138  Names should be unique to a release. So we might want to generate a name field
   139  by inserting the release name - for example:
   140  
   141  ```yaml
   142  apiVersion: v1
   143  kind: Service
   144  metadata:
   145    name: {{ .Release.Name }}-myservice
   146  ```
   147  
   148  Or if there is only one resource of this kind then we could use .Release.Name or the template fullname function defined in \_helpers.tpl (which uses release name):
   149  
   150  ```yaml
   151  apiVersion: v1
   152  kind: Service
   153  metadata:
   154    name: {{ template "fullname" . }}
   155  ```
   156  
   157  However, there may be cases where it is known that there won't be naming conflicts from a fixed name.
   158  In these cases a fixed name might make it easier for an application to find a resource such as a Service.
   159  If the option for fixed names is needed then one way to manage this might be to make the setting of the name explicit by using a service.name value from the values.yaml if provided:
   160  
   161  ```yaml
   162  apiVersion: v1
   163  kind: Service
   164  metadata:
   165    {{- if .Values.service.name }}
   166      name: {{ .Values.service.name }}
   167    {{- else }}
   168      name: {{ template "fullname" . }}
   169    {{- end }}
   170  ```
   171  
   172  ## Comments (YAML Comments vs. Template Comments)
   173  
   174  Both YAML and Helm Templates have comment markers.
   175  
   176  YAML comments:
   177  ```yaml
   178  # This is a comment
   179  type: sprocket
   180  ```
   181  
   182  Template Comments:
   183  ```yaml
   184  {{- /*
   185  This is a comment.
   186  */ -}}
   187  type: frobnitz
   188  ```
   189  
   190  Template comments should be used when documenting features of a template, such as explaining a defined template:
   191  
   192  ```yaml
   193  {{- /*
   194  mychart.shortname provides a 6 char truncated version of the release name.
   195  */ -}}
   196  {{ define "mychart.shortname" -}}
   197  {{ .Release.Name | trunc 6 }}
   198  {{- end -}}
   199  
   200  ```
   201  
   202  Inside of templates, YAML comments may be used when it is useful for Helm users to (possibly) see the comments during debugging.
   203  
   204  ```
   205  # This may cause problems if the value is more than 100Gi
   206  memory: {{ .Values.maxMem | quote }}
   207  ```
   208  
   209  The comment above is visible when the user runs `helm install --debug`, while
   210  comments specified in `{{- /* */ -}}` sections are not.
   211  
   212  ## Use of JSON in Templates and Template Output
   213  
   214  YAML is a superset of JSON. In some cases, using a JSON syntax can be more
   215  readable than other YAML representations.
   216  
   217  For example, this YAML is closer to the normal YAML method of expressing lists:
   218  
   219  ```yaml
   220  arguments: 
   221    - "--dirname"
   222    - "/foo"
   223  ```
   224  
   225  But it is easier to read when collapsed into a JSON list style:
   226  
   227  ```yaml
   228  arguments: ["--dirname", "/foo"]
   229  ```
   230  
   231  Using JSON for increased legibility is good. However, JSON syntax should not
   232  be used for representing more complex constructs.
   233  
   234  When dealing with pure JSON embedded inside of YAML (such as init container
   235  configuration), it is of course appropriate to use the JSON format.