Introduction to Named Templates
Learn how to use named templates.
We'll cover the following
Note: An interactive sandbox is located at the end of this lesson.
Named templates#
We’ve got a very simple Helm chart with only two Kubernetes resources, Deployment and Service. If we take a closer look at them we would see that even though they’re two different resources, some of their parts are the same.
For instance, they have the same labels
in a metadata
property, as shown below:
For now, it’s rather a simple one, but that’ll change once we start to add more resources and extend the existing parts. To reduce the number of duplicated parts of a code we can extract them and define them as named templates ( a template inside a template). Such templates, or as we prefer to call them, snippets, can be defined in an already existing Helm template file or a separate one and then be reused in multiple places.
The `_helpers.tpl` file#
Let’s go back to our example with labels
and create a separate named template file— _helpers.tpl
—which is located in a /templates
folder. What is important here is the name of the file. It can be whatever we would like it to be, but it needs to start with _
,otherwise, Helm will try to create a Kubernetes resource file out of it. Since it’s just a utility file that contains reusable parts we don’t want to create a Kubernetes resource out of it.
Here’s the content of a _helpers.tpl
file:
Let’s break the above snippet into smaller pieces:
The part between
{{/*
and*/}}
is a comment section that informs the user or other Helm chart developer what the purpose of a specifically named template is (it’s not mandatory, but it’s considered good practice to provide such information).{{- define "app.labels" -}}
begins the named template, containing adefine
keyword followed by a"app.labels"
which is a name of a template (it will be used later on in template files to reference a definition from here). By design, there is no limitation on how named templates can be named, but usually, their name starts with a chart name, like in our example.The actual body of the named template, which remains as it was.
{{- end }}
ends the named template, with only the parts betweendefine
andend
included in it.
Okay, so now we can add the app.labels
named template into the Service definition file (service.yaml
):
Instead of a list of labels, we have added a single line with an include
action that points out app.labels
named template.
Now, if we try to use this chart and upgrade the kanban-backend
release we would get the following result:
The output will be as follows:
Error: UPGRADE FAILED: error validating "": error validating data: [ValidationError(Service): unknown field "app" in io.k8s.api.core.v1.Service, ValidationError(Service): unknown field "app.kubernetes.io/version" in io.k8s.api.core.v1.Service, ValidationError(Service): unknown field "group" in io.k8s.api.core.v1.Service]
An upgrade didn’t happen, because we got an error in a generated template. The reason for that is that all the labels are added to the wrong indentation level. Here is how the resulting template would look like:
As we can see, even though we have added indentation to the include
action, it was not respected in a generated template. This is the tricky part that we need to always remember when using named templates.