How does "template" and "include" differ in helm

Question

How does "template" and "include" keywords differ in helm. Both seem to be used to render template parameters

Answer 1

template is part of the core Go text/template language. It always renders its results to the template output; it does not produce a value and its result cannot be captured in a variable or included in a pipeline.

include is a Helm extension. It captures the template output and returns it as a string. Its result can be used the same way as any other support function call. include is not a "keyword" or "action" or "special form", from the point of view of the templating language it is an ordinary extension function.

If you're unsure, in the context of a Helm chart, include is usually not wrong.

The most important place where this difference matters is where you have a block that produces a YAML fragment, and you need to indent it. Helm includes an indent function that can do this, but it needs a string to do this, so you need to use include and not template here.

{{- define "foo.labels" -}}
foo: bar
{{ end -}}

metadata:
  labels:
{{ include "foo.labels" . | indent 4 }}
spec:
  template:
    metadata:
{{ include "foo.labels" . | indent 8 }}

For a more direct example, consider a template that just quotes its parameter. If you call this with template, the template pipeline syntax applies to the template parameter. If you call it with include, it applies to the result of the template call. Combining this with indent, there's a visible difference whether you see the indentation inside or outside the quotes.

{{ define "quote" }}{{ quote . }}{{ end }}

{{/* "hello" is indented, then "  hello" is quoted */}}
Template: {{ template "quote" "hello" | indent 2 }}

{{/* "hello" is quoted, then '"hello"' is indented */}}
Include:  {{ include "quote" "hello" | indent 2 }}

Template: "  hello"

Include:    "hello"