Helm Templates: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
Line 219: Line 219:


A '''named template''', sometimes called a '''partial''' or a '''subtemplate''', is a template define inside of a file, and given a names. There are two different ways to create named templates, with the [[#define|define]] action and with the [[#template|template]] action.
A '''named template''', sometimes called a '''partial''' or a '''subtemplate''', is a template define inside of a file, and given a names. There are two different ways to create named templates, with the [[#define|define]] action and with the [[#template|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 [[Helm_Concepts#Subcharts|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" }}


===define===
===define===

Revision as of 23:16, 29 August 2019

External

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 - 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. Then why 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

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

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 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

Accessing Files inside Templates

Accessing Files inside Templates

TODO.

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

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 }}

Template Pipelines

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

Template Control Structures

Flow control structures are called "actions".

if/else

if/else

if/else can be used to create conditional blocks.

TODO.

with

Modifying scope using with

with specifies a scope.

TODO.

range

Looping with the range Action

range provides a "for each" loop.

TODO.

Named Template Actions

Named Templates

A named template, sometimes called a partial or a subtemplate, 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" }}

define

Declaring and Using Templates with define and template

define declares a new named template inside the current template.

TODO.

template

Declaring and Using Templates with define and template

template imports a named template.

TODO.

block

Avoid using Blocks

block declares a special kind of fillable template area.

TODO.

Setting the Scope of a Template

Setting the Scope of a Template

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.

TODO