Helm Templates: Difference between revisions
Line 164: | Line 164: | ||
=Template Pipelines= | =Template Pipelines= | ||
{{External|[https://helm.sh/docs/chart_template_guide/#pipelines Pipelines]}} | {{External|[https://helm.sh/docs/chart_template_guide/#pipelines Pipelines]}} | ||
{{ .Values.color | upper }} | |||
=TODO= | =TODO= |
Revision as of 04:31, 29 August 2019
External
- The Chart Template Developer’s Guide https://helm.sh/docs/chart_template_guide/#the-chart-template-developer-s-guide
- Go Templates: https://godoc.org/text/template
- sprig Template Functions: https://godoc.org/github.com/Masterminds/sprig
Internal
Overview
Templates are files living 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 through the template rendering engine, then collect the results and send them to to Kubernetes.
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.
It also contains the following files:
Files whose names start with "_" or "." will be ignored. - Really? helm install complained about _pod.yaml.
Template Comments
# This is a comment
{{- /* This is another comment */ -}}
Template Directives
A template directive is enclosed in {{ and }} blocks, and it is recommended to pad the directive with space at its left and right.
Simple Replacement
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.
kind: ConfigMap metadata: name: {{ .Release.Name }}-configmap
Scopes
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
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:
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 contains values passed into template from the values.yaml file and from other user sources. An existing field is available as (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 can 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.
Release
This object describes the release itself.
Release.Name
Exposes the release name:
{{ .Release.Name }}
Release.Revision
Exposes the release revision:
{{ .Release.Revision }}
Release.Time
Exposes the time of the release:
{{ .Release.Time }}
Release.Namespace
Exposes the namespace to be released info, if the manifest does not override:
{{ .Release.Namespace }}
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
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 }}
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
Template Pipelines
{{ .Values.color | upper }}
TODO
- https://helm.sh/docs/chart_best_practices/#templates
- https://helm.sh/docs/developing_charts/#templates-and-values
- https://helm.sh/docs/developing_charts/#know-your-template-functions
- https://helm.sh/docs/developing_charts/#quote-strings-don-t-quote-integers
- https://helm.sh/docs/developing_charts/#using-the-include-function
- https://helm.sh/docs/developing_charts/#using-the-required-function
- https://helm.sh/docs/developing_charts/#using-the-tpl-function
- https://helm.sh/docs/developing_charts/#creating-image-pull-secrets
- https://helm.sh/docs/developing_charts/#automatically-roll-deployments-when-configmaps-or-secrets-change
- https://helm.sh/docs/developing_charts/#tell-tiller-not-to-delete-a-resource
- https://helm.sh/docs/developing_charts/#using-partials-and-template-includes
- https://helm.sh/docs/chart_best_practices/#pods-and-podtemplates
- https://helm.sh/docs/chart_best_practices/#images
- https://helm.sh/docs/chart_best_practices/#imagepullpolicy
- https://helm.sh/docs/chart_best_practices/#podtemplates-should-declare-selectors