Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 38 ยท Template Functions and Pipelines

Rendering YAML: toYaml, indent and nindent

Turn values into YAML blocks with toYaml, place them at the right depth with indent and nindent, avoid the classic indentation errors and convert with toJson and fromYaml.

Charts constantly need to copy a chunk of values, such as resources, nodeSelector or tolerations, straight into a manifest. Writing each field by hand would limit what users can configure, so charts pass the whole structure through. The trio toYaml, indent and nindent does it. Getting the indentation right is the most frequent source of broken charts, so this lesson explains the mechanics and the patterns that work every time.

toYaml

toYaml turns any value (map, list, string, number) into YAML text:

YAML
resources:
  {{- toYaml .Values.resources | nindent 2 }}

With resources set to {limits: {cpu: 500m, memory: 256Mi}, requests: {cpu: 100m}} the output is:

YAML
resources:
  limits:
    cpu: 500m
    memory: 256Mi
  requests:
    cpu: 100m

Facts to remember about its output:

  • Keys are sorted alphabetically, regardless of the order in values.yaml.
  • There is no trailing newline (Helm's toYaml trims it), which is what makes it pipeable.
  • It produces multi-line text, so it must be indented to the depth where it is inserted.
  • An empty map becomes {} and an empty list [], strings that look like numbers or booleans are quoted, and long strings may wrap.

The companions are toJson / toPrettyJson, fromYaml (parse a YAML string into a map, for example the content of a file) and fromJson. toYaml can also be used to dump . or .Values while debugging.

indent and nindent

indent N adds N spaces in front of every line of a string. nindent N does the same and starts with a newline:

For the two-line text a: 1 / b: 2, indent 2 returns a: 1 and b: 2 joined by a newline, while nindent 2 returns the same text with an extra newline in front.

Since a multi-line block must start on a fresh line under its parent key, nindent is the one you use almost always, together with {{- on the left so the template's own newline is removed:

YAML
spec:
  template:
    spec:
      {{- with .Values.nodeSelector }}
      nodeSelector:
        {{- toYaml . | nindent 8 }}
      {{- end }}

Read it slowly. {{- toYaml . | nindent 8 }} first removes the newline before the action ({{-), then nindent 8 adds a newline and indents each line with eight spaces, which is the depth of the children of nodeSelector:. The number you pass is the column the content must start in, counted in the final YAML, not relative to the template.

flowchart LR
  V["Map from values"] --> Y["toYaml: multi-line text"]
  Y --> N["nindent N: newline + N spaces per line"]
  N --> O["Inserted under the parent key"]

Choose N so that the children line up under their parent key.

A stand-in for toYaml and nindent

The program below writes a small toYaml (sorted keys, quoting of ambiguous strings) and the two indent functions, then renders a Deployment fragment. Change nindent numbers and see what breaks.

Python Stand-in: toYaml, indent and nindent

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.

Notice three details in the output: keys came out sorted (limits before requests, cpu before memory), the empty map is printed as {} and the string "true" kept its quotes.

Patterns that always work

Optional block (skip when empty):

YAML
{{- with .Values.tolerations }}
tolerations:
  {{- toYaml . | nindent 8 }}
{{- end }}

A list that sits under a key with a leading dash: toYaml of a list yields lines starting with - , so indent the whole block to the same depth as the key, or one level deeper:

YAML
      containers:
        - name: web
          {{- with .Values.extraEnv }}
          env:
            {{- toYaml . | nindent 12 }}
          {{- end }}

Merging free-form map and fixed keys: build a dictionary first and dump it once:

YAML
{{- $labels := merge (dict "app" "web") .Values.extraLabels }}
labels:
  {{- toYaml $labels | nindent 4 }}

Inline value: for a single scalar do not use nindent; write key: {{ .Values.x }} or key: {{ .Values.x | quote }}.

A helper that returns YAML is inserted the same way: {{- include "webapp.labels" . | nindent 4 }}.

Debugging indentation

  1. Render and look at the exact text: helm template . -s templates/deployment.yaml.
  2. Count the spaces of the parent key in the rendered file and add 2 for its children; that is your nindent argument.
  3. If you see error converting YAML to JSON: yaml: line 31: did not find expected key, the block is indented to the wrong depth, or a - line was misaligned.
  4. If you see blank lines inside your block, a -}} or {{- is missing.
  5. If a value turns out as a number when it should be text, quote it or use toString/quote before dumping.

The stand-in below shows what happens with a wrong depth: the YAML stays valid but the structure changes, which is the sneaky case that reaches the cluster.

Python Stand-in: the effect of a wrong nindent

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.

With 4 spaces, cpu and memory are children of limits. With 2 they become siblings of limits, and with 0 the YAML is simply invalid. Only the first is correct, and only a parse (or a schema check, see the Testing chapter) tells the difference.

Do not put {{- toYaml ... }} in the middle of a line, such as limits: {{ toYaml .Values.limits }}. Multi-line output on a single key line produces invalid YAML. Use {{ toJson ... }} for a one-line flow-style value, which is valid YAML as well.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between indent 4 and nindent 4?

    nindent prepends a newline and then indents every line, so the block starts on its own line.
  2. 2. Which statement about toYaml output is true?

    Sorted keys and no trailing newline make toYaml predictable and pipeable.
  3. 3. A block under nodeSelector: at column 6 should have its children at column 8. Which call?

    The number is the column where the lines must start in the rendered YAML.
  4. 4. How do you avoid emitting 'tolerations:' with an empty value?

    with skips the block when the value is empty, so no dangling key is rendered.

Summary

  • toYaml converts values to sorted, trailing-newline-free YAML; toJson, fromYaml and fromJson convert other ways.
  • nindent N starts a new line and indents each line by N; N is the target column in the rendered YAML.
  • Wrap optional blocks in with and use {{- so no blank lines or empty keys remain.
  • A wrong indentation count can still be valid YAML with the wrong structure, so verify with helm template and lint.

Next: Required, Default and Validation