Helm charts

Tags:

Summary

This are my notes on how to build functioning helm charts.

Getting started

Create a new skeleton chart:

helm create generic-chart

where generic-chart is the name of the chart.

Verify the chart syntax

helm lint generic-chart

Installing a chart

helm install [NAME] [CHART] [flags]

NAME is how you will refer to your application in Kubernetes. CHART is the name of the application’s helm chart. See helm install --help for a list of all the flags and their meanings. For example:

helm install demo ./generic-chart

Viewing application configuration

To see the configuration that was sent to Kubernetes during installation run:

helm get manifest [NAME]

For example:

helm get manifest demo

Note: The output is in YAML format.

Debugging a chart

To see what will be sent to Kubernetes without actually sending it, run:

helm install [NAME] [CHART] --debug --dry-run

NAME is how you will refer to your application in Kubernetes. CHART is the name of the application’s helm chart. --debug and --dry-run are two (2) of the many flags that can be passed. See Installing a chart above for information on the flags.

helm install demo ./generic-chart --debug --dry-run

File structure of a chart

Top level

Charts.yaml

values.yaml

List of specificity order for ingesting values

Note that bigger numbers override smaller numbers

  1. The values.yaml file in the chart
  2. If this is a subchart, the values.yaml file of a parent chart
  3. A values file if passed into helm install or helm upgrade with the -f flag (helm install -f myvals.yaml ./mychart)
  4. Individual parameters passed with –set (such as helm install –set foo=bar ./mychart)

Templates directory

This directory is in the top level of your chart. It contains various files that are important to the setup and management of the Kubernetes application. helm parses each file performing variable substitution, then passes the final output to Kubernetes for implementation.

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

NOTES.txt

The “help text” for your chart. This will be displayed to your users when they run helm install.

deployment.yaml

A basic manifest for creating a Kubernetes deployment

service.yaml

A basic manifest for creating a service endpoint for your deployment

_helpers.tpl

A place to put template helpers that you can re-use throughout the chart

configmap.yaml

A ConfigMap is simply an object for storing configuration data.

Built-in template objects

  • Objects are referenced in Object Dot Notation. Example: .Release.Name
  • This refers to the Name object in the Release object in the top-level object (.).
  • By convention, built-in objects start with a capital letter and local objects start with a lower case letter.

Release

  • This object describes the release itself. It has several objects inside of it.

Name

  • The name given on the command line during installation.

Namespace

  • The namespace to be released into if the manifest doesn’t override.
  • Often this will be default but, can be any string.

IsUpgrade

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

IsInstall

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

Revision

  • The revision number for this release.
  • On install, this is 1, and it is incremented with each upgrade and rollback.

Service

  • The service that is rendering the present template.
  • On Helm, this is always Helm.

Values

  • Values passed into the template from the values.yaml file and from user-supplied files.
  • By default, Values is empty.

Chart

  • The contents of the Chart.yaml file.
  • Any data in Chart.yaml will be accessible here.
  • For example {{ .Chart.Name }}-{{ .Chart.Version }} will print out demo-0.1.0.
  • The available fields are listed in the Charts Guide

Files

  • This provides access to all non-special files in a chart.
  • While you cannot use it to access templates, you can use it to access other files in the chart.
  • See the section Accessing Files for more information.

Get

  • is a function for getting a file by name
  • Example: .Files.Get config.ini

GetBytes

  • is a function for getting the contents of a file as an array of bytes instead of as a string.
  • This is useful for things like images.

Glob

  • is a function that returns a list of files whose names match the given shell glob pattern.

Lines

  • is a function that reads a file line-by-line.
  • This is useful for iterating over each line in a file.

AsSecrets

  • is a function that returns the file bodies as Base 64 encoded strings.

AsConfig

  • is a function that returns file bodies as a YAML map.

Capabilities

  • This provides information about what capabilities the Kubernetes cluster supports.

APIVersions

  • is a set of versions.

Has

  • $version indicates whether a version (e.g., batch/v1) or resource (e.g., apps/v1/Deployment) is available on the cluster.

KubeVersion

  • is the Kubernetes version.

Version

  • is the Kubernetes version.

Major

  • is the Kubernetes major version.

Minor

  • is the Kubernetes minor version.

HelmVersion

  • is the object containing the Helm Version details.
  • it is the same output of helm version

Version

  • is the current Helm version in semver format.

GitCommit

  • is the Helm git sha1.

GitTreeState

  • is the state of the Helm git tree.

GoVersion

  • is the version of the Go compiler used.

Template

  • Contains information about the current template that is being executed

Name

  • A namespaced file path to the current template (e.g. mychart/templates/mytemplate.yaml)

BasePath

  • The namespaced path to the templates directory of the current chart (e.g. mychart/templates).

Template functions

  • Best practice: When injecting strings from the .Values object into the template, we ought to quote these strings. We can do that by calling the quote function. Example: food: {{ quote .Values.favorite.food }}
  • Template functions follow the syntax, functionName arg1 arg2...
  • Helm has over 60 available functions. Some of them are defined by the Go template language itself. Most of the others are part of the Sprig template library.

Pipelines

  • Pipelines are a tool for chaining together a series of template commands to compactly express a series of transformations. Example: food: {{ .Values.favorite.food | upper | quote }}

default function

  • This function allows you to specify a default value inside of the template, in case the value is omitted. Example: drink: {{ .Values.favorite.drink | default "tea" | quote }}
  • Note, all static default values should live in the values.yaml
  • Use the default function for computed default values. Example: drink: {{ .Values.favorite.drink | default (printf "%s-tea" (include "fullname" .)) }}

lookup function

  • This function can be used to look up resources in a running cluster.

    lookup apiVersion, kind, namespace, name -> resource or resource list
    Parameter Type Required
    apiVersion string Y
    kind string Y
    namespace string N
    name string N

  • When the requested object is not found, an empty value is returned. This can be used to check for the existence of an object.

  • When lookup returns an object, it will return a dictionary. This dictionary can be further navigated to extract specific values.

  • When lookup returns a list of objects, it is possible to access the object list via the items field. Example:

    {{ range $index, $service := (lookup "v1" "Service" "mynamespace" "").items }}
    {{/* do something with each service */}}
{{ end }}

Template categories

See