Helm Templates: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
(85 intermediate revisions by the same user not shown)
Line 9: Line 9:
* [[Helm Concepts#Templates|Helm Concepts]]
* [[Helm Concepts#Templates|Helm Concepts]]
* [[helm install]]
* [[helm install]]
* [[Helm Named Template Recipes|Named Template Recipes]]


=Overview=
=Overview=


Templates are files living under a chart's [[#The_templates.2F_Directory|templates/ directory]]. They are written in YAML with Helm templates extensions. Upon processing by Helm, they become [[Kubernetes Manifests|Kubernetes manifest files]]. Helm template extensions are written in the Help template language, which is based on Go templates.
Templates are a set of Kubernetes parameterized manifests that form an application. They live under a chart's [[#The_templates.2F_Directory|templates/ directory]]. They are written in YAML with Helm templates extensions. Upon processing by Helm, they become [[Kubernetes Manifests|Kubernetes manifest files]]. Helm template extensions are written in the Help template language, which is based on Go templates.


=The templates/ Directory=
=The templates/ Directory=
Line 21: Line 22:


The files whose name begins with an underscore ('_') are assumed to not have a manifest inside, so they are not rendered into manifest definitions. However, they are available everywhere within other chart templates for use. These files are conventionally used to store [[#Partial|partials]] and helpers. [[Helm Chart _helpers.tpl|_helpers.tpl]] is the default location for template [[#Partial|partials]].
The files whose name begins with an underscore ('_') are assumed to not have a manifest inside, so they are not rendered into manifest definitions. However, they are available everywhere within other chart templates for use. These files are conventionally used to store [[#Partial|partials]] and helpers. [[Helm Chart _helpers.tpl|_helpers.tpl]] is the default location for template [[#Partial|partials]].
==<span id='Order'></span>Installation and De-Installation Order==
During installation, Helm collects all of the resources in a given chart and its dependences, groups them by resource type, and installs them in the order specified here https://github.com/helm/helm/blob/release-2.14/pkg/tiller/kind_sorter.go#L29-L57. Upon de-installation the order is reversed: https://github.com/helm/helm/blob/release-2.14/pkg/tiller/kind_sorter.go#L62-L90


=Template Comments=
=Template Comments=


<syntaxhighlight lang='yaml'>
  # This is a comment
  # This is a comment
</syntaxhighlight>
<syntaxhighlight lang='yaml'>
{{/* Generate basic labels */}}
</syntaxhighlight>


====Multi-Line Comments====
<syntaxhighlight lang='yaml'>
  {{- /*
  {{- /*
  This is another comment
  This is another  
multi-line
comment
  */ -}}
  */ -}}
</syntaxhighlight>


=<span id='Template_Directive'></span>Template Directives=
=<span id='Template_Directive'></span>Template Directives=


A template directive is enclosed in &#123;{ and }} blocks, and it is recommended to pad the directive with space at its left and right.  
A template directive, sometimes also referred as tag, is enclosed in &#123;{ and }} blocks, and it is recommended to pad the directive with space at its left and right.  
==Simple Replacement==
<span id='Simple_Replacement'></span>The simplest directive renders a value. A value is a namespaced object, where each dot (.) separates each namespaced element. A leading dot indicates that we start with the top-most namespace for the [[#Scope|scope]].
 
The simplest directive is a value, which is a namespaced object, where each dot (.) separates each namespaced element. A leading dot indicates that we start with the top-most namespace for the [[#Scope|scope]].


  kind: ConfigMap
  kind: ConfigMap
  metadata:
  metadata:
   name: &#123;{ .Release.Name }}-configmap
   name: &#123;{ .Release.Name }}-configmap
Directives may also include [[#Template_Function|functions]] and other constructs.
With the exception of the [[#Multi-Line_Comments|multi-line comments]], all directives must be specified on one line only. Space present inside a directive is irrelevant, the following formats are equivalent:
<syntaxhighlight lang='yaml'>
{{.Values.color}}
{{ .Values.color }}
{{            .Values.color              }}
</syntaxhighlight>
The recommended format is to allow for a space after '&#123;{' and before '}}':
<syntaxhighlight lang='yaml'>
{{ .Values.color }}
</syntaxhighlight>
==Directives and Whitespace Handling==
{{External|[https://helm.sh/docs/chart_template_guide/#controlling-whitespace Controlling Whitespace]}}
The spaces inside a directive is irrelevant (we cannot have newlines inside a directive, all directives must be specified on a single line).
The '&#123;{' and '}}' directive delimiters, without any other modifications, leave the template whitespace surrounding them alone, and do not interfere with it in any way. A hyphen '-' placed after the '&#123;{' delimiter or before the '}}' delimiter instructs the rendering engine to trim the whitespace preceding, respectively trailing the delimiter. Whitespace includes spaces, tabs, newline ('\n') and carriage return ('\r'). When encountering "-", the template engine will simply drop the corresponding whitespace until a non-whitespace character is found.
<syntaxhighlight lang='yaml'>
metadata:
  color: {{ .Values.color }}
spec:
</syntaxhighlight>
will produce (assuming that "color" is declared to be "blue" in values.yaml:
<syntaxhighlight lang='yaml'>
metadata:
  color: blue
spec:
</syntaxhighlight>
To trim preceding whitespace, use '&#123;{-'.
<syntaxhighlight lang='yaml'>
metadata:
  color: {{- .Values.color }}
spec:
</syntaxhighlight>
will produce:
<syntaxhighlight lang='yaml'>
metadata:
  color:blue
spec:
</syntaxhighlight>
To trim trailing whitespace (whitespace includes newlines), use '-}}'.
<syntaxhighlight lang='yaml'>
metadata:
  color: {{ .Values.color -}}
spec:
</syntaxhighlight>
will produce:
<syntaxhighlight lang='yaml'>
metadata:
  color: bluespec:
</syntaxhighlight>
(which is something you most like don't want).
For details related to whitespace handling when declaring named templates, see [[Helm_Templates#Named_Templates_and_Whitespace_Handling|Named Templates and Whitespace Handling]], below.


=<span id='Scope'></span>Scopes=
=<span id='Scope'></span>Scopes=
Line 54: Line 138:


{{External|[https://helm.sh/docs/chart_template_guide/#built-in-objects Built-in Objects]}}
{{External|[https://helm.sh/docs/chart_template_guide/#built-in-objects Built-in Objects]}}
Built-in objects are a way to access several types of values, some of which are directly configured by operators - in values.yaml, for example -, while others are generated dynamically by Helm or taken from other parts of the chart.


The built-in values always begin with a capital letter, based on Go's naming convention. For a fully working examples of built-in objects replacement see: {{External|https://github.com/ovidiuf/playground/tree/master/helm/bactrosaurus}}
The built-in values always begin with a capital letter, based on Go's naming convention. For a fully working examples of built-in objects replacement see: {{External|https://github.com/ovidiuf/playground/tree/master/helm/bactrosaurus}}
Line 67: Line 153:
===Values===
===Values===


This object contains values passed into template from the [[Helm Chart values.yaml|values.yaml]] file and from [[Helm_Concepts#Values_and_Chart_Configuration|other user sources]]. An existing field is available as (note leading dot) <tt>.Values.<''fieldName''></tt>. Unlike in [[#Chart|Chart]]'s case, the fields are allowed to keep their original capitalization. For example, a value declared as such in <tt>values.yaml</tt>:
This object provides access the effective values of all configuration element, as present in the [[Helm_Configuration#Runtime_Configuration_Tree|runtime configuration tree]], and it essentially exposes the chart configuration to templates. The value of an existing configuration element can be access using the following syntax: (note leading dot) <code>.Values.<''fieldName''></code>. Unlike in [[#Chart|Chart]]'s case, the fields are allowed to keep their original capitalization. For example, a value declared as such in <tt>values.yaml</tt>:


size: 10
<syntaxhighlight lang='yaml'>
size: 10
</syntaxhighlight>


can be references in a template as:
can be references in a template as:


kind: ConfigMap
<syntaxhighlight lang='yaml'>
...
kind: ConfigMap
data:
...
  size: &#123;{ .Values.size }}
data:
  size: {{ .Values.size }}
</syntaxhighlight>


Values can contain structured content:
Values may contain structured content:


characteristics:
<syntaxhighlight lang='yaml'>
  size: 10
characteristics:
  shape: "large"
  size: 10
  shape: "large"
</syntaxhighlight>


can be referenced in template as:
can be referenced in template as:


kind: ConfigMap
<syntaxhighlight lang='yaml'>
kind: ConfigMap
  ...
  ...
data:
data:
  size: &#123;{ .Values.characteristics.size }}
  size: {{ .Values.characteristics.size }}
  shape: &#123;{ .Values.characteristics.shape }}
  shape: {{ .Values.characteristics.shape }}
</syntaxhighlight>
While structuring data this way is possible, the recommendation is to keep values trees shallow, favoring flatness.


While structuring data this way is possible, the recommendation is to keep values trees shallow, favoring flatness.
In case the structure contains an array, individual elements can be referred from the template with the [[#Accessing_Array_Elements|index function]].


===Release===
===Release===
Line 99: Line 194:
Exposes the [[Helm_Concepts#Release_Name|release name]]:
Exposes the [[Helm_Concepts#Release_Name|release name]]:
  &#123;{ .Release.Name }}
  &#123;{ .Release.Name }}
 
====Release.Namespace====
Exposes the namespace the release made into:
&#123;{ .Release.Namespace }}
====Release.Revision====
====Release.Revision====
Exposes the [[Helm_Concepts#Release_Revision|release revision]]:
Exposes the [[Helm_Concepts#Release_Revision|release revision]]:
Line 106: Line 203:
Exposes the time of the release:
Exposes the time of the release:
  &#123;{ .Release.Time }}
  &#123;{ .Release.Time }}
====Release.Namespace====
Exposes the namespace to be released info, if the manifest does not override:
&#123;{ .Release.Namespace }}
====Release.IsUpgrade====
====Release.IsUpgrade====
This is set to true if the current operation is an upgrade or rollback.
This is set to true if the current operation is an upgrade or rollback.
Line 128: Line 222:


====Accessing Files inside Templates====
====Accessing Files inside Templates====
{{External|[https://helm.sh/docs/chart_template_guide/#accessing-files-inside-templates Accessing Files inside Templates]}}
{{Internal|Helm_install#Accessing_Arbitrary_Files_inside_Templates|Accessing Arbitrary Files inside Templates}}
<font color=darkgray>TODO.</font>


===Capabilities===
===Capabilities===
Line 147: Line 240:
  &#123;{ .Template.BasePath }}
  &#123;{ .Template.BasePath }}


=Template Functions=
=Data Types=
{{External|https://helm.sh/docs/chart_template_guide/data_types/}}
 
* string: A string of text
* bool: a true or false
* int: an integer value
* float64: a 64-bit floating point value
* a byte slice ([]byte), used to hold potentially binary data
* struct: an object with properties and methods
* a slice (indexed list) of one of the previous types
* a string-keyed map (map[string]interface{}) where the value is one of the previous types.
 
The easiest way to debug an object's type is to pass it through <code>printf "%t"</code> in a template, which will print the type. Also see the [[Helm Template Function typeOf|typeOf]] and [[Helm Template Function kindOf|kindOf]] functions.
 
=<span id='Template_Function'></span>Template Functions=


{{External|[https://helm.sh/docs/chart_template_guide/#template-functions-and-pipelines Template Functions and Pipelines]}}
{{External|[https://helm.sh/docs/chart_template_guide/#template-functions-and-pipelines Template Functions and Pipelines]}}
Line 168: Line 275:
* <span id='repeat'></span>[[Helm Template Function Repeat|repeat]]
* <span id='repeat'></span>[[Helm Template Function Repeat|repeat]]
* <span id='upper'></span>[[Helm Template Function Upper|upper]]
* <span id='upper'></span>[[Helm Template Function Upper|upper]]
* now
* htmlDate
* replace "+" "_"
* trunc 63
* trimSuffix "-"
* indent 4
* [[Helm Template Function nindent|nindent]]
* [[#Accessing_Array_Elements|index]]
* <span id='toYaml'></span>[[Helm Template Function toYaml|toYaml]]
* <span id='list'></span>[[Helm Template Function List|list]]
* <span id='title'></span>[[Helm Template Function Title|title]]
* <span id='typeOf'></span>[[Helm Template Function typeOf|typeOf]]
* <span id='kindOf'></span>[[Helm Template Function kindOf|kindOf]]
===Operators===
===Operators===
{{External|[https://helm.sh/docs/chart_template_guide/#operators-are-functions Operators are Functions]}}
{{External|[https://helm.sh/docs/chart_template_guide/#operators-are-functions Operators are Functions]}}
Line 180: Line 301:
   &#123;{ or }}
   &#123;{ or }}
   &#123;{ not }}
   &#123;{ not }}
===Accessing Array Elements===
To access a specific element of an array data structure, use the <tt>index</tt> function. The <tt>index</tt> function is 0-based.
Assuming we declare a simple array:
<syntaxhighlight lang='yaml'>
colors:
  - 'blue'
  - 'red'
  - 'green'
</syntaxhighlight>
then the first element of the array can be accessed with:
<syntaxhighlight lang='yaml'>
{{ index .Values.colors 0 }}
</syntaxhighlight>
The directive is rendered to "blue".
When the array contains maps:
<syntaxhighlight lang='yaml'>
colors:
  - name: blue
    shade: dark
  - name: red
    shade: light
</syntaxhighlight>
the fields of the maps can be accessed with - note (...):
<syntaxhighlight lang='yaml'>
{{ (index .Values.colors 0).name }}
</syntaxhighlight>
This pattern can be extrapolated to more complex data structures.


=Template Pipelines=
=Template Pipelines=
Line 194: Line 353:
==if/else==
==if/else==


{{External|[https://helm.sh/docs/chart_template_guide/#if-else if/else]}}
{{Internal|Helm Template If/Else|if/else}}
 
<tt>if</tt>/<tt>else</tt> can be used to create conditional blocks.
 
<font color=darkgray>TODO.</font>


==with==
==with==
{{External|[https://helm.sh/docs/chart_template_guide/#modifying-scope-using-with Modifying scope using <tt>with</tt>]}}
{{External|[https://helm.sh/docs/chart_template_guide/#modifying-scope-using-with Modifying scope using <tt>with</tt>]}}


<tt>with</tt> specifies a [[#Scope|scope]].
<code>with</code> narrows the scope of the context for better readability and more expressive template blocks.  <tt>with</tt> specifies a [[#Scope|scope]]:
 
<syntaxhighlight lang='yaml'>
{{- with .Values.deployment }}
strategy:
  rollungUpdate:
    maxUnavailable: {{ .maxUnavailable }}
    maxSurge: {{ .maxSurge }}
revisionHistoryLimit: {{ .revisionHistoryLimit }}
minReadySeconds: {{ .minReadySeconds }}
{{- end }}
</syntaxhighlight>


<font color=darkgray>TODO.</font>
<font color=darkgray>TODO.</font>


==range==
==range==
{{External|[https://helm.sh/docs/chart_template_guide/#looping-with-the-range-action Looping with the <tt>range</tt> Action]}}
{{Internal|Helm Template range|range}}
 
<tt>range</tt> provides a "for each" loop.
 
<font color=darkgray>TODO.</font>


==Named Template Actions==
==Named Template Actions==
Line 231: Line 393:
{{External|[https://helm.sh/docs/chart_template_guide/#declaring-and-using-templates-with-define-and-template Declaring and Using Templates with <tt>define</tt>]}}
{{External|[https://helm.sh/docs/chart_template_guide/#declaring-and-using-templates-with-define-and-template Declaring and Using Templates with <tt>define</tt>]}}


<tt>define</tt> declares a new named template inside of a template file:
<tt>define</tt> declares a new named template inside of a template file, conventionally [[Helm Chart _helpers.tpl|_helpers.tpl]]:


<syntaxhighlight lang='yaml'>
<syntaxhighlight lang='yaml'>
{{/* Generate basic labels */}}
{{- define "mychart.labels" }}
{{- define "mychart.labels" }}
   labels:
   labels:
Line 240: Line 403:
{{- end }}
{{- end }}
</syntaxhighlight>
</syntaxhighlight>
By convention, define functions should have a simple documentation block &#123;{/* ... */}} describing what they do.


The body of the partial may include directives.
The body of the partial may include directives.
Partials may be used instead of variables, by declaring a template that acts like a variable:
<syntaxhighlight lang='yaml'>
{{/*
Compute the service name that depends on the release name. This partial should be inlined every time the service name is needed.
*/}}
{{- define "myChart.postgresqlServiceName" -}}
{{- printf "%s-postgresql" .Release.Name -}}
{{- end -}}
</syntaxhighlight>
When we need the service name in a template, we render it as such:
<syntaxhighlight lang='yaml'>
... {{ template "myChart.postgresqlServiceName" . }} ...
</syntaxhighlight>
For more details on rendering, see [[#template|template]] below.
====Named Templates and Whitespace Handling====
Unless controlled with '&#123;{-' and '-}}', the whitespace specified inside the partial are preserved and projected in the rendered result.
====Named Template Recipes====
{{Internal|Helm Named Template Recipes|Named Template Recipes}}


===template===
===template===
{{External|[https://helm.sh/docs/chart_template_guide/#declaring-and-using-templates-with-define-and-template Declaring and Using Templates with <tt>template</tt>]}}


<tt>template</tt> imports a named template.
A partial defined as such can be embedded inside other template with the [[#template|template]] action:


<font color=darkgray>TODO.</font>
<syntaxhighlight lang='yaml'>
kind: ConfigMap
metadata:
name: ...
{{- template "mychart.labels" }}
...
</syntaxhighlight>
 
When the template engine reads the file that contains the partial, it will store away the reference to "mychart.labels" until template "mychart.labels" is called. Then it will render that template inline. After rendering, the result will look like this:
<syntaxhighlight lang='yaml'>
kind: ConfigMap
metadata:
name: ...
labels:
  generator: helm
  date: 2019-08-29
...
</syntaxhighlight>
 
<span id='Setting_the_Scope_of_a_Template'></span>'''Setting the Scope of a Template'''. The "template" action allows passing a [[#Scope|scope]]. By default, no scope is passed by default, so objects like .Chart.Name are not found and rendered to blank space.
 
To pass the scope of the calling template, use "template" as such (note the dot):
<syntaxhighlight lang='yaml'>
...
{{- template "mychart.labels" . }}
...
</syntaxhighlight>
 
In the above example, we passed the top-level (".") scope. We can pass whatever scope (template object) we want:
 
<syntaxhighlight lang='yaml'>
...
{{- template "mychart.labels" .Values }}
...
</syntaxhighlight>
 
or:
 
<syntaxhighlight lang='yaml'>
...
{{- template "mychart.labels" .Values.favorite }}
...
</syntaxhighlight>


===block===
===block===
Line 255: Line 488:
<tt>block</tt> declares a special kind of fillable template area.
<tt>block</tt> declares a special kind of fillable template area.


<font color=darkgray>TODO.</font>
=Setting the Scope of a Template=
{{External|[https://helm.sh/docs/chart_template_guide/#setting-the-scope-of-a-template Setting the Scope of a Template]}}
<font color=darkgray>TODO.</font>
<font color=darkgray>TODO.</font>


Line 267: Line 496:
=Template Variables=
=Template Variables=


{{External|[https://helm.sh/docs/chart_template_guide/#variables Variables]}}
{{External|[https://helm.sh/docs/chart_template_guide/variables/ Variables]}}
<font color=darkgray>TODO.</font>
<font color=darkgray>TODO.</font>


Line 279: Line 508:


<font color=darkgray>TODO.</font>
<font color=darkgray>TODO.</font>
=Template Recipes=
==Transfer the Content of a Map from values.yaml to a Template==
values.yaml:
<syntaxhighlight lang='yaml'>
data:
  color: 'red'
  shape: 'triangle'
</syntaxhighlight>
template:
<syntaxhighlight lang='yaml'>
metadata:
  {{- if .Values.data }}
  annotations:
  {{- range $key, $value := .Values.data}}
    {{ $key }}: {{ $value | quote }}
  {{- end}}
  {{- end}}
</syntaxhighlight>
For more details see: {{Internal|Helm_Template_range#Iterating_over_a_Map|range}}
==Transfer the Content of a List from values.yaml to a Template==
{{Internal|Helm_Template_range#Iterating_over_a_.Values_List|Iterating over a .Values List}}


=TODO=
=TODO=

Revision as of 00:51, 27 June 2020

External

Internal

Overview

Templates are a set of Kubernetes parameterized manifests that form an application. They live under a chart's templates/ directory. They are written in YAML with Helm templates extensions. Upon processing by Helm, they become Kubernetes manifest files. Helm template extensions are written in the Help template language, which is based on Go templates.

The templates/ Directory

The 'templates' directory contains templates that, after combination with values, will the Kubernetes manifests. When Tiller evaluates a chart, it will send all of the files in the directory - with a few exceptions - through the template rendering engine, then collect the results and send them to to Kubernetes. Note that the NOTES.txt and _helpers.tpl files are also subject to template rendering, but they are not sent to Kubernetes as manifests.

Template names do not follow a rigid naming pattern. It is, however, recommended to use the suffix .yaml for YAML files and .tpl for helpers.

The files whose name begins with an underscore ('_') are assumed to not have a manifest inside, so they are not rendered into manifest definitions. However, they are available everywhere within other chart templates for use. These files are conventionally used to store partials and helpers. _helpers.tpl is the default location for template partials.

Installation and De-Installation Order

During installation, Helm collects all of the resources in a given chart and its dependences, groups them by resource type, and installs them in the order specified here https://github.com/helm/helm/blob/release-2.14/pkg/tiller/kind_sorter.go#L29-L57. Upon de-installation the order is reversed: https://github.com/helm/helm/blob/release-2.14/pkg/tiller/kind_sorter.go#L62-L90

Template Comments

 # This is a comment
{{/* Generate basic labels */}}

Multi-Line Comments

 {{- /*
 This is another 
 multi-line
 comment
 */ -}}

Template Directives

A template directive, sometimes also referred as tag, is enclosed in {{ and }} blocks, and it is recommended to pad the directive with space at its left and right. The simplest directive renders a value. A value is a namespaced object, where each dot (.) separates each namespaced element. A leading dot indicates that we start with the top-most namespace for the scope.

kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-configmap

Directives may also include functions and other constructs.

With the exception of the multi-line comments, all directives must be specified on one line only. Space present inside a directive is irrelevant, the following formats are equivalent:

{{.Values.color}}
{{ .Values.color }}
{{            .Values.color               }}

The recommended format is to allow for a space after '{{' and before '}}':

{{ .Values.color }}

Directives and Whitespace Handling

Controlling Whitespace

The spaces inside a directive is irrelevant (we cannot have newlines inside a directive, all directives must be specified on a single line). The '{{' and '}}' directive delimiters, without any other modifications, leave the template whitespace surrounding them alone, and do not interfere with it in any way. A hyphen '-' placed after the '{{' delimiter or before the '}}' delimiter instructs the rendering engine to trim the whitespace preceding, respectively trailing the delimiter. Whitespace includes spaces, tabs, newline ('\n') and carriage return ('\r'). When encountering "-", the template engine will simply drop the corresponding whitespace until a non-whitespace character is found.

metadata:
  color: {{ .Values.color }}
spec:

will produce (assuming that "color" is declared to be "blue" in values.yaml:

metadata:
  color: blue
spec:

To trim preceding whitespace, use '{{-'.

metadata:
  color: {{- .Values.color }}
spec:

will produce:

metadata:
  color:blue
spec:

To trim trailing whitespace (whitespace includes newlines), use '-}}'.

metadata:
  color: {{ .Values.color -}}
spec:

will produce:

metadata:
  color: bluespec:

(which is something you most like don't want).

For details related to whitespace handling when declaring named templates, see Named Templates and Whitespace Handling, below.

Scopes

Scopes are declared with 'with'.

TODO.

Template Objects

Objects are passed into a template from the template engine. The template directives can create new objects and pass them around. There are also built-in objects, which are made available by default. Objects can be simple - have just one value -, or they can contain other objects or functions. For example the "Release" built-in object contains several other objects (like "Release.Name"). The "Files" object contains functions.

Built-in Objects

Built-in Objects

Built-in objects are a way to access several types of values, some of which are directly configured by operators - in values.yaml, for example -, while others are generated dynamically by Helm or taken from other parts of the chart.

The built-in values always begin with a capital letter, based on Go's naming convention. For a fully working examples of built-in objects replacement see:

https://github.com/ovidiuf/playground/tree/master/helm/bactrosaurus

Chart

This object contains value passed into the template from the Chart.yaml file. An existing field is available as (note leading dot) .Chart.<UpperCasedFirstLetterFieldName>. It is important to capitalize the first letter of the field name, otherwise the directive evaluation fails.

Example:

{{ .Chart.Name }}
{{ .Chart.Version }}

Values

This object provides access the effective values of all configuration element, as present in the runtime configuration tree, and it essentially exposes the chart configuration to templates. The value of an existing configuration element can be access using the following syntax: (note leading dot) .Values.<fieldName>. Unlike in Chart's case, the fields are allowed to keep their original capitalization. For example, a value declared as such in values.yaml:

size: 10

can be references in a template as:

kind: ConfigMap
...
data:
  size: {{ .Values.size }}

Values may contain structured content:

characteristics:
  size: 10
  shape: "large"

can be referenced in template as:

kind: ConfigMap
 ...
data:
  size: {{ .Values.characteristics.size }}
  shape: {{ .Values.characteristics.shape }}

While structuring data this way is possible, the recommendation is to keep values trees shallow, favoring flatness.

In case the structure contains an array, individual elements can be referred from the template with the index function.

Release

This object describes the release itself.

Release.Name

Exposes the release name:

{{ .Release.Name }}

Release.Namespace

Exposes the namespace the release made into:

{{ .Release.Namespace }}

Release.Revision

Exposes the release revision:

{{ .Release.Revision }}

Release.Time

Exposes the time of the release:

{{ .Release.Time }}

Release.IsUpgrade

This is set to true if the current operation is an upgrade or rollback.

{{ .Release.IsUpgrade }}

Release.IsInstall

This is set to true if the current operation is an install.

{{ .Release.IsInstall }}

Release.Service

Exposes the releasing service - always Tiller

Files

The object provide access to all non-special files in the chart. It cannot be used to access templates. The access is provided via several functions:

Files.Get

{{ .Files.Get <file-name> }}

Files.GetBytes

Accessing Files inside Templates

Accessing Arbitrary Files inside Templates

Capabilities

Provides information about the capabilities of the Kubernetes cluster:

{{ .Capabilities.APIVersions }}
{{ .Capabilities.APIVersions.Has }}
{{ .Capabilities.KubeVersion }}
{{ .Capabilities.KubeVersion.Major|
 Minor|GitVersion|GitCommit|GitTreeState|BuildDate|GoVersion|Compiler|Platform}}
{{ .Capabilities.TillerVersion }}

Template

Contains information about the current template that is being executed:

{{ .Template.Name }}
{{ .Template.BasePath }}

Data Types

https://helm.sh/docs/chart_template_guide/data_types/
  • string: A string of text
  • bool: a true or false
  • int: an integer value
  • float64: a 64-bit floating point value
  • a byte slice ([]byte), used to hold potentially binary data
  • struct: an object with properties and methods
  • a slice (indexed list) of one of the previous types
  • a string-keyed map (map[string]interface{}) where the value is one of the previous types.

The easiest way to debug an object's type is to pass it through printf "%t" in a template, which will print the type. Also see the typeOf and kindOf functions.

Template Functions

Template Functions and Pipelines
Go Templates
sprig Template Functions

A template function modifies data provided to the template via template objects, and it is declared inside the template, in a template directive. Template functions follow the syntax:

functionName arg1 arg2 ...

Example:

{{ quote .Values.color }}

Helm Template Function Reference

Operators

Operators are Functions

Operators are implemented as functions that return a boolean value:

 {{ eq Values.color "blue" }}
 {{ ne }}
 {{ lt }}
 {{ gt }}
 {{ and }}
 {{ or }}
 {{ not }}

Accessing Array Elements

To access a specific element of an array data structure, use the index function. The index function is 0-based.

Assuming we declare a simple array:

colors:
  - 'blue'
  - 'red'
  - 'green'

then the first element of the array can be accessed with:

{{ index .Values.colors 0 }}

The directive is rendered to "blue".

When the array contains maps:

colors:
  - name: blue
    shade: dark
  - name: red
    shade: light

the fields of the maps can be accessed with - note (...):

{{ (index .Values.colors 0).name }}

This pattern can be extrapolated to more complex data structures.

Template Pipelines

Pipelines
{{ <object> | <function1> | <function2>  }}
{{ .Values.color | upper | repeat 5 }}

Template Control Structures

Flow control structures are called "actions".

if/else

if/else

with

Modifying scope using with

with narrows the scope of the context for better readability and more expressive template blocks. with specifies a scope:

{{- with .Values.deployment }}
strategy:
  rollungUpdate:
    maxUnavailable: {{ .maxUnavailable }}
    maxSurge: {{ .maxSurge }}
revisionHistoryLimit: {{ .revisionHistoryLimit }}
minReadySeconds: {{ .minReadySeconds }}
{{- end }}

TODO.

range

range

Named Template Actions

Named Templates

A named template, sometimes called a partial, a subtemplate or an embedded template, is a template define inside of a file, and given a names. There are two different ways to create named templates, with the define action and with the template action.

Template names are global. That means if two template are declared with the same name, whichever is loaded last will be the one that will be used. Moreover, the templates in subcharts, which we are not necessarily too familiar with, are compiled together with top-level templates, so it is possible to run into template name collisions we are not aware of. For this reason, it is a good practice to name your templates with unique, chart-specific names.

One popular naming convention is to prefix the name of each defined template with the name of the chart:

{{ define "mychart.labels" }}

If everyone follows the same convention, chart-specific named templates get their own namespace and that decreases the probability of conflict that may arise due to two different charts that implement templates with the same name.

define

Declaring and Using Templates with define

define declares a new named template inside of a template file, conventionally _helpers.tpl:

{{/* Generate basic labels */}}
{{- define "mychart.labels" }}
  labels:
    generator: helm
    date: {{ now | htmlDate }}
{{- end }}

By convention, define functions should have a simple documentation block {{/* ... */}} describing what they do.

The body of the partial may include directives.

Partials may be used instead of variables, by declaring a template that acts like a variable:

{{/*
Compute the service name that depends on the release name. This partial should be inlined every time the service name is needed.
*/}}
{{- define "myChart.postgresqlServiceName" -}}
{{- printf "%s-postgresql" .Release.Name -}}
{{- end -}}

When we need the service name in a template, we render it as such:

 ... {{ template "myChart.postgresqlServiceName" . }} ...

For more details on rendering, see template below.

Named Templates and Whitespace Handling

Unless controlled with '{{-' and '-}}', the whitespace specified inside the partial are preserved and projected in the rendered result.

Named Template Recipes

Named Template Recipes

template

A partial defined as such can be embedded inside other template with the template action:

kind: ConfigMap
metadata:
 name: ...
 {{- template "mychart.labels" }}
...

When the template engine reads the file that contains the partial, it will store away the reference to "mychart.labels" until template "mychart.labels" is called. Then it will render that template inline. After rendering, the result will look like this:

kind: ConfigMap
metadata:
 name: ...
 labels:
   generator: helm
   date: 2019-08-29
...

Setting the Scope of a Template. The "template" action allows passing a scope. By default, no scope is passed by default, so objects like .Chart.Name are not found and rendered to blank space.

To pass the scope of the calling template, use "template" as such (note the dot):

 ...
 {{- template "mychart.labels" . }}
 ...

In the above example, we passed the top-level (".") scope. We can pass whatever scope (template object) we want:

 ...
 {{- template "mychart.labels" .Values }}
 ...

or:

 ...
 {{- template "mychart.labels" .Values.favorite }}
 ...

block

Avoid using Blocks

block declares a special kind of fillable template area.

TODO.

The include Function

The include Function

TODO.

Template Variables

Variables

TODO.

Configmap and Secrets Utility Functions

Configmap and Secrets Utility Functions

TODO.

Debugging Templates

Debugging Templates
https://github.com/databus23/schelm

TODO.

Template Recipes

Transfer the Content of a Map from values.yaml to a Template

values.yaml:

data:
  color: 'red'
  shape: 'triangle'

template:

metadata:
  {{- if .Values.data }}
  annotations:
  {{- range $key, $value := .Values.data}}
    {{ $key }}: {{ $value | quote }}
  {{- end}}
  {{- end}}

For more details see:

range

Transfer the Content of a List from values.yaml to a Template

Iterating over a .Values List

TODO