Helm Semantics

helm.md

Helm Semantics

Helm Commands

Install

$ helm install --dry-run --debug ./mychart
$ helm install --dry-run --debug --set favoriteDrink=slurm ./mychart
$ helm install --dry-run --debug --namespace foo --tiller-namespace foo --name my-chart .

Upgrade

$ helm upgrade --namespace foo --tiller-namespace foo --wait --install --version 0.1.2 --name my-chart

Render

$ helm template --name foobar .

Package

$ helm package .

Variables

Builtin Variables

• Release.Name: the release name
• Release.Time: the time of the release
• Release.Namespace: the namespace to be released into (if the manifest doesn’t override)
• Release.Service: the name of the releasing service (always Tiller).
• Release.Revision: the revision number of this release. It begins at 1 and is incremented for each helm upgrade.
• Release.IsUpgrade: this is set to true if the current operation is an upgrade or rollback.
• Release.IsInstall: this is set to true if the current operation is an install.
• Chart.Name: Chart.yaml name value
• Chart.Version: Chart.yaml version value
• Chart.Maintainers: Chart.yaml maintainers value

Scope

The scope of variables is redefined within statements (loop, control structure, named templates). It means that . (.Release.Foobar ...) isn't available or redefined inside the statement.

The special $ is always binded to root scope, for example $.Release.Name is still valid within a loop or a if statements.

Usage

Interpolate variable with:

{{ .Release.Name }}
{{ .Values.key }}

Assign variable:

{{- $relname := .Release.Name -}}

Functions

Function call:

{{ functionName arg1 arg2...}}
{{ quote .Values.key }}

Pipelines

Pipelines call and chaining:

{{ .Values.key | quote }}
{{ .Values.key | upper | quote }}
{{ .Values.key | default "tea" | quote }}

Flow Control

Control Structure

• if/else

{{ if PIPELINE }}
  # Do something
{{ else if OTHER PIPELINE }}
  # Do something else
{{ else }}
  # Default case
{{ end }}

• with

{{- with .Values.map }}
  drink: {{ .drink | default "tea" | quote }}
  food: {{ .food | upper | quote }}
{{- end }}

• range

{{- range .Values.list }}
    - {{ . | title | quote }}
{{- end }}

{{- range $index, $topping := .Values.pizzaToppings }}
  {{ $index }}: {{ $topping }}
{{- end }}

Named Templates (functions)

• define declares a new named template
• template imports a named template
• block declares a special kind of fillable template area

Define a named template someNamedTemplate usually in _helpers.tpl:

{{- define "someNamedTemplate" -}}
  {{ functions ...}}
{{- end -}}

Render someNamedTemplate and pass the current scope with . (accessing builtin objects):

{{ template "mychart.someNamedTemplate" . }}

template is an action and not a function; pipelining is not supported.

Include someNamedTemplate and pass the current scope with . (accessing builtin objects):

{{- include "mychart.someNamedTemplate" . | nindent 4 }}

include is a function and support pipelining to other functions like nindent.

Operators

The operator is placed at the front of the statement.

Operators list:

• eq
• ne
• lt
• gt
• and
• or
• not

{{/* true when the variable .Values.key exists and is set to "foo" */}}
{{ if and .Values.key (eq .Values.fooString "foo") }}
    {{ ... }}
{{ end }}

{{/* true when the variable .Values.key is set or .values.notkey is not set */}}
{{ if or .Values.key (not .Values.notkey) }}
   {{ ... }}
{{ end }}

Whitespace

{{- text -}}

{{ indent 2 "mug:true" }}

Best Practices

Chart Name

1. lowercase letters and numbers
2. start with a letter
3. no uppercase letters
4. no underscore
5. directory is the same as chart name

Ressource Labels

Name	Status	Description
app.kubernetes.io/name	REC	This should be the app name, usually {{ template "name" . }} Not Helm-specific.
helm.sh/chart	REC	This should be the chart name and version: {{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}.
app.kubernetes.io/managed-by	REC	This should always be {{ .Release.Service }}. It is for finding all things managed by Tiller.
app.kubernetes.io/instance	REC	This should be {{ .Release.Name }}. Differentiating between different instances of the same application.
app.kubernetes.io/version	OPT	The version of the app and can be set to {{ .Chart.AppVersion }}.
app.kubernetes.io/component	OPT	Marking the different roles that pieces may play in an application.
app.kubernetes.io/part-of	OPT	When multiple charts or pieces of software are used together to make one application.

• REC: recommended
• OPT: optional

Links

• https://godoc.org/text/template
• https://godoc.org/github.com/Masterminds/sprig
• https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/