Why do Helm charts write `toYaml .Values.resources | nindent 12` rather than `indent 12`?

## Three pieces, one idiom The expression `{{- toYaml .Values.resources | nindent 12 }}` is doing three separate jobs, and the interview question is really about whether you can name them. `toYaml` takes a value out of `.Values` — a map, a list, a scalar — and serialises it as YAML text. The output starts at column zero, carries no leading indentation of its own, and has no trailing newline. That last property is deliberate and useful: it means the spliced block does not push a stray blank line into the manifest. `indent` and `nindent` then place that text. `indent 12` prefixes twelve spaces to every line of the string, first line included. `nindent 12` prefixes a newline to the whole thing and then indents every line by twelve. The `n` is for the newline; the indentation behaviour is identical. The leading `{{-` deletes the whitespace sitting in front of the action in the template file, including the newline that ended the previous line. ## Why the first line is the whole problem A splice is written where the value belongs, so the action is indented in the template to match its surroundings: ```yaml resources: {{ toYaml .Values.resources | indent 12 }} ``` Those twelve literal spaces before `{{` are real text and are emitted. Then `indent 12` adds twelve more to the first line of the serialised value. The first key of the block therefore lands at column twenty-four while every following key lands at column twelve. A mapping whose first key is deeper than its siblings is not a valid block mapping, and the render fails when Helm parses it. Swapping in `nindent` and adding the leading trim marker fixes both halves at once: ```yaml resources: {{- toYaml .Values.resources | nindent 12 }} ``` The dash removes the newline and the twelve literal spaces, `nindent` puts the newline back, and every line of the value — first one included — gets exactly twelve spaces. What the template looks like and what the output looks like are now decoupled, which is why the pairing has become the house style of essentially every published chart. ## Picking the number The number is the column the block's keys must occupy in the rendered document, not a relative offset. Count the parent key's indentation in the output and add two: a container's `resources:` sitting at ten under `containers:` needs its keys at twelve. It is a rendered-document measurement, so when a chart body is assembled from partials, the reliable way to check it is to read the render rather than the template. ## When indent is still correct `indent` is not a legacy spelling. It is right whenever the action begins at column zero of its template line, because then there is no literal indentation to double up and no newline to reinsert. It is also right when you are indenting a string you have already assembled with its own leading newline. The rule of thumb: if there is whitespace between the start of the line and the `{{`, you want the trim marker and `nindent`. ## The edge cases that surprise people An empty map serialises to `{}` and an empty list to `[]`, each on a single line. `nindent 12` will happily place that on its own line, so `resources:` ends up holding an empty map rather than being absent. That is usually harmless, but authors who want the key gone entirely guard the whole block instead of relying on the indentation functions to make it disappear. A single-key value hides mistakes. If the block has exactly one line, the `indent`-after-literal-spaces bug produces a line that is merely deeper than it needs to be, and extra depth under a key means nothing in YAML — so it parses and works. The same chart breaks the moment someone supplies two keys. A chart that has been fine for months can fail on a values change for exactly this reason. Finally, the pipeline order is not cosmetic. `toYaml .Values.resources | nindent 12` serialises first and indents the resulting text. Reversing it makes no sense: `nindent` works on a string, so it must be downstream of whatever produced the string. ## What good looks like In review, three things are worth checking on any splice: that the action carries a leading trim marker, that it uses `nindent` rather than `indent`, and that the number matches the parent's column in the rendered output rather than in the template. Those three checks catch nearly every indentation defect a chart can have before it reaches a cluster.