Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 38 ยท Templates and Values

Named Templates and _helpers.tpl

Reuse template code with define and include: build helpers in _helpers.tpl, pass context and custom dicts, avoid name collisions and know include versus template.

If you copy the same block of labels into six templates, you will forget to update one of them. Helm solves this with named templates: snippets you define once, give a name and insert anywhere. The file templates/_helpers.tpl is where charts conventionally keep them. This lesson covers define, include, passing context, naming rules and the traps around global scope.

define and include

A named template is created with define and used with include:

YAML
{{/* templates/_helpers.tpl */}}
{{- define "webapp.labels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}
YAML
# templates/deployment.yaml
metadata:
  name: {{ .Release.Name }}
  labels:
    {{- include "webapp.labels" . | nindent 4 }}

Three details matter:

  1. The dot you pass is the context inside. include "webapp.labels" . hands over the current context, which is why .Chart and .Release work inside the definition. If you pass something else, such as .Values.image, the definition sees that as its dot.
  2. include returns a string, so you can pipe it: | nindent 4, | quote, | sha256sum. That is why include is preferred over the older template action.
  3. _helpers.tpl produces no output. Files that start with an underscore are loaded for their definitions only.

include versus template

Go templates have a built-in {{ template "name" . }} action. It inserts the text directly and cannot be piped, so the indentation of multi-line helpers cannot be fixed. Helm adds the include function that returns a string instead. Rule of thumb: always use include.

template "x" . include "x" .
Pipe into other functions no yes (`
Store in a variable no yes ($x := include ...)
Use inside other expressions no yes

The classic helpers

The generated _helpers.tpl defines these, and many charts copy them:

YAML
{{- define "webapp.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{- define "webapp.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

{{- define "webapp.selectorLabels" -}}
app.kubernetes.io/name: {{ include "webapp.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

Notice how a helper can call another with include, and how the dashes ({{-, -}}) keep the returned string free of stray newlines. The mistake to avoid is a returned string that begins or ends with a newline, which breaks the YAML indentation where it is used.

Passing more than the dot

A named template receives exactly one argument. To give it several, build a map with dict:

YAML
{{- define "webapp.probe" -}}
httpGet:
  path: {{ .path }}
  port: {{ .port }}
initialDelaySeconds: {{ .delay | default 5 }}
{{- end }}
YAML
livenessProbe:
  {{- include "webapp.probe" (dict "path" "/healthz" "port" "http") | nindent 2 }}
readinessProbe:
  {{- include "webapp.probe" (dict "path" "/ready" "port" "http" "delay" 10) | nindent 2 }}

When the helper also needs the top-level context, add it to the dict and use .root: (dict "root" . "name" "worker"), then {{ .root.Release.Name }} inside. This pattern builds one template that renders several similar objects (for example one Deployment per component).

Namespacing: all names are global

Every define in the whole chart and all its subcharts lives in one global namespace. If two charts define "labels", the last one loaded wins, silently changing the other chart's output. The convention that prevents this is to prefix every helper with the chart name: webapp.labels, redis.labels. Never write a bare define "labels".

The stand-in models a registry of templates and shows what happens with a collision. It also shows how include passes a context.

Python Stand-in: a registry of named templates

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second output has lost the parent's labels. With chart-prefixed names the two definitions would have been different keys.

Overriding and defaults

Because definitions are global, a parent chart can override a subchart's helper by defining the same name, which is occasionally used on purpose. You can also give a helper a default body that users may replace with block:

YAML
{{- block "webapp.extraEnv" . }}
- name: DEFAULT
  value: "1"
{{- end }}

block defines and immediately uses the template. It is rare; most charts use plain define plus values.

Real-world helper ideas

  • Image reference with optional registry prefix and tag fallback:
YAML
{{- define "webapp.image" -}}
{{- $registry := .Values.global.imageRegistry | default .Values.image.registry -}}
{{- $tag := .Values.image.tag | default .Chart.AppVersion -}}
{{- if $registry -}}
{{ printf "%s/%s:%s" $registry .Values.image.repository $tag }}
{{- else -}}
{{ printf "%s:%s" .Values.image.repository $tag }}
{{- end -}}
{{- end }}
  • Service account name: the configured name, or the fullname when create is true, otherwise default.
  • Pod annotations with checksums so that a changed ConfigMap rolls the pods.
  • A validation helper that calls fail when an invalid combination is configured (see Required, Default and Validation).

Here the image helper is reproduced, so you can try combinations of registry and tag.

Python Stand-in: an image helper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Debugging helpers

  • Render a single file: helm template . -s templates/deployment.yaml.
  • Print what a helper returns by using it in a ConfigMap data field while experimenting.
  • The error template: no template "webapp.fullname" associated with template "gotpl" means the name is misspelled or the chart that defines it is not loaded.
  • A YAML error in the rendered output right where a helper is used usually means a stray newline or wrong nindent count.

Keep helpers small and single-purpose, document them with a {{/* */}} comment above each define (name, arguments, what they return), and keep one _helpers.tpl per concern for large charts (_labels.tpl, _images.tpl).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is include preferred over the template action?

    template inserts text directly and cannot be piped; include returns a string.
  2. 2. Why should helper names be prefixed with the chart name?

    A later definition silently replaces an earlier one with the same name.
  3. 3. How do you pass several arguments to a named template?

    A named template takes one context value; dict packs several into one.
  4. 4. What does a file named _helpers.tpl render on its own?

    Files starting with an underscore are not rendered as manifests.

Summary

  • define "chart.name" creates a named template; include "chart.name" . returns it as a string you can pipe.
  • The argument you pass becomes the dot inside the helper; use dict to pass several values.
  • Names are global across the chart and its subcharts, so prefix them with the chart name.
  • Keep helpers free of stray newlines and use nindent where they are inserted.

Next: Functions and Pipelines