Helm Named Templates

External

• https://helm.sh/docs/chart_template_guide/named_templates/

Internal

• Helm Templates

Overview

A named template, also known as a partial, sub-template or embedded template, is a fragment of text that is declared in one file and then rendered in-line into another template, usually defined in a different file, every time it is invoked with the template action or the include function. A sub-template is declared with the define action. A sub-template name has a name, declared when the sub-template is defined. The sub-template body may contain action and function declarations, which will be rendered when the enclosing template is rendered. When the template engine reads the sub-template declaration, it will store away the reference to the sub-template, keyed by its name, until it encounters a template action or a include function that specify the sub-template name. At that time, it will render the sub-template inline.

Sub-Template Elements

Sub-Template Name

Sub-template names, including those declared in subcharts, are global. This means that if two sub-templates have the same name, whichever is loaded last will be the one to be used. For this reason, is a good practice to name the sub-templates with chart-specific names, and prefix the name of the sub-template with the name of the chart:

{{ define "mychart.mysubtemplate" }}

Using the chart name as a prefix, chart-specific sub-templates get their own namespace and that decreases the probability of conflict that may arise due to two different charts that implement templates with the same name.

Sub-Template Files

Sub-templates can be declared inside other template files, in helper files, for example _helpers.tpl, inside the chart's templates/ directory. _helpers.tpl is the default location for small sub-templates. If a sub-template is large enough, it can be stored in its own '_'-prefixed file. For more details on templates/ directory and template file conventions, see:

templates/

Actions

define

https://helm.sh/docs/chart_template_guide/named_templates/#declaring-and-using-templates-with-define-and-template

The 'define' action is used to declare the name and the content of the sub-template:

{{/* Generate basic labels */}}
{{- define "mychart.mysubtemplate" }}
  labels:
    color: blue
    date: {{ now | htmlDate }}
{{- end }}

Note that the indentation of the sub-template body is important. The template action will render the body as is, honoring the existing indentation. The include function can be used to indent the body, by piping it through the indent function. However, the indent function will only add extra indentation to the already existing one.

By convention, a "define" declaration should be preceded by a documentation block that describes what it does. The body of the sub-template may include directive. "define" declaration does not produce output, until the sub-template is rendered with template or include.

template

The 'template' action renders the specified sub-template, with the given scope, in the enclosing template.

...
kind: ConfigMap
metadata:
  name: test-cm
  {{- template "mychart.mysubtemplate" . }}
...

Note that "template" renders the sub-template body as is, reflecting the original indentation. The action output cannot be changed, and that is why the input function is almost always a better option to embed a sub-template.

include Function

The "include" function is the preferred alternative to embed a template. The output of the function can be processed by a pipeline before embedding, hence the indentation can be controlled, unlike in template case.

...
kind: ConfigMap
metadata:
  name: test-cm
  {{- include "mychart.mysubtemplate" . | indent 2 }}
...

TODEPLETE

tmp