Templates

This part of the Best Practices Guide focuses on templates.

Structure of templates/

The templates/ directory should be structured as follows:

  • Template files should have the extension .yaml if they produce YAML output.The extension .tpl may be used for template files that produce no formattedcontent.
  • Template file names should use dashed notation (my-example-configmap.yaml),not camelcase.
  • Each resource definition should be in its own template file.
  • Template file names should reflect the resource kind in the name. e.g.foo-pod.yaml, bar-svc.yaml

Names of Defined Templates

Defined templates (templates created inside a {{ define }} directive) areglobally accessible. That means that a chart and all of its subcharts will haveaccess to all of the templates created with {{ define }}.

For that reason, all defined template names should be namespaced.

Correct:

  1. {{- define "nginx.fullname" }}
  2. {{/* ... */}}
  3. {{ end -}}

Incorrect:

  1. {{- define "fullname" -}}
  2. {{/* ... */}}
  3. {{ end -}}

It is highly recommended that new charts are created via helm create commandas the template names are automatically defined as per this best practice.

Formatting Templates

Templates should be indented using two spaces (never tabs).

Template directives should have whitespace after the opening braces and beforethe closing braces:

Correct:

  1. {{ .foo }}
  2. {{ print "foo" }}
  3. {{- print "bar" -}}

Incorrect:

  1. {{.foo}}
  2. {{print "foo"}}
  3. {{-print "bar"-}}

Templates should chomp whitespace where possible:

  1. foo:
  2.   {{- range .Values.items }}
  3.   {{ . }}
  4.   {{ end -}}

Blocks (such as control structures) may be indented to indicate flow of thetemplate code.

  1. {{ if $foo -}}
  2.   {{- with .Bar }}Hello{{ end -}}
  3. {{- end -}}

However, since YAML is a whitespace-oriented language, it is often not possiblefor code indentation to follow that convention.

Whitespace in Generated Templates

It is preferable to keep the amount of whitespace in generated templates to aminimum. In particular, numerous blank lines should not appear adjacent to eachother. But occasional empty lines (particularly between logical sections) isfine.

This is best:

  1. apiVersion: batch/v1
  2. kind: Job
  3. metadata:
  4.   name: example
  5.   labels:
  6.     first: first
  7.     second: second

This is okay:

  1. apiVersion: batch/v1
  2. kind: Job
  4. metadata:
  5.   name: example
  7.   labels:
  8.     first: first
  9.     second: second

But this should be avoided:

  1. apiVersion: batch/v1
  2. kind: Job
  4. metadata:
  5.   name: example
  11.   labels:
  12.     first: first
  14.     second: second

Comments (YAML Comments vs. Template Comments)

Both YAML and Helm Templates have comment markers.

YAML comments:

  1. # This is a comment
  2. type: sprocket

Template Comments:

  1. {{- /*
  2. This is a comment.
  3. */ -}}
  4. type: frobnitz

Template comments should be used when documenting features of a template, suchas explaining a defined template:

  1. {{- /*
  2. mychart.shortname provides a 6 char truncated version of the release name.
  3. */ -}}
  4. {{ define "mychart.shortname" -}}
  5. {{ .Release.Name | trunc 6 }}
  6. {{- end -}}

Inside of templates, YAML comments may be used when it is useful for Helm usersto (possibly) see the comments during debugging.

  1. # This may cause problems if the value is more than 100Gi
  2. memory: {{ .Values.maxMem | quote }}

The comment above is visible when the user runs helm install —debug, whilecomments specified in {{- / / -}} sections are not.

Use of JSON in Templates and Template Output

YAML is a superset of JSON. In some cases, using a JSON syntax can be morereadable than other YAML representations.

For example, this YAML is closer to the normal YAML method of expressing lists:

  1. arguments:
  2.   - "--dirname"
  3.   - "/foo"

But it is easier to read when collapsed into a JSON list style:

  1. arguments: ["--dirname", "/foo"]

Using JSON for increased legibility is good. However, JSON syntax should not beused for representing more complex constructs.

When dealing with pure JSON embedded inside of YAML (such as init containerconfiguration), it is of course appropriate to use the JSON format.