Helm Packaging and Templating

helm-packaging-and-templating.md

Helm Packaging and Templating

• Helm Packaging and Templating
  • Chart Creation
    • Chart.yaml
    • charts
    • values.yaml
    • templates
      • Notes.txt
      • _helper.tpl (template partial)
      • tests
  • Templating
    • Built-in Objects
      • Release
      • Values
      • Charts
      • Files
      • Capabilities
      • Template
    • include
    • {{- }} Chomp whitespace
    • {{ | }} Pipe Symbol
    • indent and nindent String functions
    • $ Root Context

Chart Creation

• package of yaml files containing all resources necessary to deploy an simple or full stack application
• folder name is always the name of the chart (without versioning)
• uses GO templating engine

.
├── Chart.yaml      # meta data and info
├── charts          # chart dependencies
├── values.yaml     # values for templates/chart
└── templates       # templated manifests

Chart.yaml

• top level metadata
• type can be application or library

apiVersion: v2
name: cloudacademy-app  # mandatory
description: CloudAcademy Custom Chart 2020
type: application
version: 0.1.0          # mandatory
appVersion: 1.16.0

charts

• contains other charts that this chart depends on

values.yaml

• structured list of default values
• injected into template before rendering

templates

• contains all the templates that will be rendered
• specifies default values
• useful for specifying environments like dev, test, prod

# values.yaml
name: my-app
container:
  name: my-app-container
  image: my-app-image
  port: 9001

# templates/deployment.yaml
apiVersion: v1
kind: Pod
metadata:
  name: {{ .Values.name }}
spec:
  containers:
  - name: {{ .Values.container.name }}
  - image: {{ .Values.container.image }}
  - port: {{ .Values.container.port }}

Notes.txt

• contains end user instructions for deployment
• instructions are output when executing helm update or helm install
• this file can also include templating

_helper.tpl (template partial)

• always begins with underscore to indicate this file doesn't output a manifest
• includes code snippets that can be used in other templates
• equivalent to factoring out code into functions for reuse elsewhere

tests

• includes tests that are used to validate the chart post deployment
• should be designed to return zero exit code indicating the test passed

Templating

Built-in Objects

• passed into templates from template engine
• Helm: Built-in Objects

Release

• describes the release itself

# examples
{{ .Release.Name }}
{{ .Release.Namespace }}
{{ .Release.IsUpgrade }}
{{ .Release.IsInstall }}
{{ .Release.Revision }}   # revision number, 1 on install
{{ .Release.Service }}    # always Helm.

Values

• reference contents of values.yaml

# examples
{{ .Values.name }}
{{ .Values.container.name }}
{{ .Values.container.image }}
{{ .Values.container.port }}

Charts

# examples
{{ .Chart.Version }}
{{ .Chart.Name }}
{{ .Chart.AppVersion }}
{{ .Chart.Description }}
{{ .Chart.Home }}
{{ .Chart.Icon }}
{{ .Chart.Sources }}
{{ .Chart.Maintainers }}
{{ .Chart.Keywords }}
{{ .Chart.URLs }}

Files

# get filenames
{{ .Files.Get }}

# get contents of a file as an array of bytes
# e.g. images
{{ .Files.GetBytes  }}

# returns a list of files whose names match the given shell glob pattern
{{ .Files.Glob }}

# iterate over a file line-by-line
{{ .Files.Lines }}

# return file contents as Base 64 encoded strings
{{ .Files.AsSecrets }}

# return file contents as YAML
{{ .Files.AsConfig }}

Capabilities

# examples
{{ .Capabilities.APIVersions }}
{{ .Capabilities.APIVersions.Has }}
{{ .Capabilities.KubeVersion }}
{{ .Capabilities.KubeVersion.Version }}
{{ .Capabilities.KubeVersion.Major }}
{{ .Capabilities.KubeVersion.Minor }}
{{ .Capabilities.HelmVersion }}
{{ .Capabilities.HelmVersion.Version }}
{{ .Capabilities.HelmVersion.GitCommit }}
{{ .Capabilities.HelmVersion.GitTreeState }}
{{ .Capabilities.HelmVersion.GoVersion }}

Template

# examples
{{ .Template.Name }}
{{ .Template.BasePath }}

include

• used to reference a template partial (.tpl)
• . indicates 'passed in scope' and can be navigated using dot notation

{{ include "webserver.fullname" . }}

{{- }} Chomp whitespace

• dash character can be used at either end (or both) depending on where you want whitespace removed

{{ | }} Pipe Symbol

• takes output of left hand side and passes it into the right hand side template function
• often used with indent and nindent functions
• can be used multiple times within a template directive

indent and nindent String functions

• ensures correct indentation is used in the template rendering
• nindent prepends a starting newline character

$ Root Context

• global variable that always points to root context

{{ $.Template.BasePath }}