Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 38 ยท Templates and Values

Go Templates: The Basics

Learn the Go template syntax behind Helm charts: actions, the dot, comments, whitespace trimming, quoting and why indentation matters when templating YAML.

Everything inside the templates/ folder of a chart is a text file with pieces of Go template syntax mixed in. Helm does not understand YAML while it templates; it just fills in text, and only afterwards parses the result as YAML. That one fact explains most template bugs. This lesson teaches the syntax you need first, and the next lessons build on it with values, objects, control flow and functions.

Actions and the dot

Anything between double curly braces is an action. Everything outside is copied unchanged.

YAML
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-config
data:
  greeting: {{ .Values.greeting }}

The leading dot is the current context. At the top of a template the dot is an object with these top-level keys: .Values, .Release, .Chart, .Capabilities, .Template, .Files and .Subcharts. Reading .Values.greeting means "the key greeting inside Values". Names are case-sensitive: .Values.Greeting is a different key. Built-in objects like .Release start with a capital letter by convention; your own values usually start lowercase.

A missing key does not stop the render: {{ .Values.nothing }} prints nothing (Helm turns Go's <no value> into an empty string). That is convenient and also dangerous, because a typo yields a silently empty field. Later lessons show required and schemas to guard against it.

Comments and quoting

YAML
{{- /* This comment disappears from the output */ -}}
{{/* and this one too */}}

Template comments are removed at render time. A YAML # comment inside a template is not removed; it ends up in the manifest. Use {{/* */}} for notes about the template itself and # for notes you want to see in the rendered YAML.

String literals use double quotes inside actions: {{ "hello" }}. The result is plain text with no quotes, so when you need quotes in the YAML, write them around the action or use the quote function (see Functions and Pipelines):

YAML
version: "{{ .Chart.AppVersion }}"     # quotes written in the YAML
version: {{ .Chart.AppVersion | quote }} # quote function

Quoting matters because YAML guesses types. Unquoted yes, no, on, off, 1e3, 0123 and true become booleans or numbers. If a value is a string that must stay a string (a version such as 1.10, a port named "8080" in an environment variable, a label value), quote it.

Whitespace control

Template actions leave their own line break behind. Without care, you get blank lines, which YAML tolerates, or worse, broken indentation. The trim markers {{- and -}} remove whitespace (including newlines) before or after the action:

  • {{- removes all whitespace to its left.
  • -}} removes all whitespace to its right.
  • The marker must touch the braces and be separated from the action by a space: {{- if ... -}}, never {{-if}}.
Python Stand-in: a tiny template renderer with trim markers

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.

Look at the two outputs. The plain comment leaves an empty line; with a left trim marker the line break before it is removed, so no blank line remains. The real Go engine is far richer, but the whitespace rules are the same.

When whitespace is part of the syntax

YAML uses indentation for structure, so rendered text must be indented correctly. A frequent pattern is a block that is only included sometimes:

YAML
spec:
  replicas: 2
  {{- if .Values.paused }}
  paused: true
  {{- end }}
  strategy: Recreate

The {{- on the if line eats the newline before it, so no blank line appears when the condition is false; and when true, the paused: true line keeps its own indentation. A leading {{- on every control line is the standard style. Avoid -}} on the right except when you intentionally join lines, because it can glue the next line onto this one.

Seeing what you get

When a template misbehaves, render it:

Terminal
helm template blog ./webapp --debug
helm template blog ./webapp --show-only templates/configmap.yaml -s templates/service.yaml
helm install blog ./webapp --dry-run --debug

--debug prints the generated manifest even if the YAML is invalid, so you can see the broken line. A typical error looks like this:

TEXT
Error: YAML parse error on webapp/templates/configmap.yaml: error converting YAML to JSON: yaml: line 7: mapping values are not allowed in this context

The line number refers to the rendered output, not your template, so always look at the rendered text. Another stage of error messages comes from the template engine itself: function "foo" not defined, nil pointer evaluating interface {}.bar (you accessed a key of something missing, such as .Values.image.tag when image does not exist).

Escaping braces

If the output needs literal {{ }}, for example for a Prometheus alert template or a Grafana dashboard, print them as strings:

YAML
summary: {{ "{{ $labels.instance }}" }} is down

The outer action prints a string that contains braces. Larger blocks can use a raw string: {{`{{ $labels.instance }}`}}.

The two stages

flowchart LR
  T["Template text with {{ }} actions"] -->|"Go template engine + values"| Y["Plain text"]
  Y -->|"YAML parser"| O["Kubernetes objects"]
  Y -.->|"mistakes show up here"| E["YAML error with line number of the output"]

Template syntax errors come from the first stage, indentation and type errors from the second.

Because stage one is plain text substitution, Helm will happily produce YAML that is valid but wrong, such as a number where Kubernetes wants a string. Linting and --dry-run=server (Upgrade Flags) catch those.

A second experiment: quoting decides the type

The stand-in below parses simple key: value lines the way YAML 1.1 does, to show what an unquoted value turns into.

Python Stand-in: what YAML makes of unquoted values

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.

no becoming False is the classic "Norway problem". Quote anything that must be text.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a leading dot in {{ .Values.replicas }} refer to?

    The dot is the current context; at the top of a template it holds the built-in objects.
  2. 2. Which text removes the newline before an action?

    {{- trims whitespace on the left; -}} on the right. The dash must touch the braces and be followed by a space.
  3. 3. You render a template and see a YAML error on line 12. Where is line 12?

    The YAML parser sees the rendered text, so line numbers refer to it.
  4. 4. How do you keep the string 1.10 from being read as a number?

    Unquoted 1.10 becomes the float 1.1; quoting keeps it a string.
  5. 5. What does a missing value such as {{ .Values.nope }} print?

    Helm prints nothing for missing keys, which can hide typos.

Summary

  • Templates are text with {{ }} actions; the dot is the current context and .Values, .Release, .Chart are its top-level keys.
  • Comments use {{/* */}}; whitespace is trimmed with {{- and -}}.
  • Helm templates text first and parses YAML second, so indentation and quoting are your responsibility.
  • Use helm template --debug and --dry-run to see the rendered output, whose line numbers errors refer to.

Next: Values and Overrides