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/

Sub-Template Scope

If a sub-template includes references to built-in objects, those objects need to be reachable from the scope the sub-template is invoked from. The scope in which the template is invoke is specified as the second argument of template or include invocation, after the sub-template name:

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 white space and 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 }}
...

Sub-templates as Variables

Sub-templates may be used instead of variables, by declaring a template that acts like a variable:

{{/*
Compute the service name that depends on the release name. This partial should be inlined every time the service name is needed.
*/}}
{{- define "myChart.postgresqlServiceName" -}}
{{- printf "%s-postgresql" .Release.Name -}}
{{- end -}}

When we need the service name in a template, we render it as such:

 ... {{ template "myChart.postgresqlServiceName" . }} ...

Recipes

Named Template Recipes

TODEPLETE

tmp