Helm Concepts

Internal

• Helm
• Helm Templates
• Helm Dependencies

Overview

Helm is a tool for managing Kubernetes packages called charts. Helm creates new charts from scratch, packages charts into chart archives (tgz) files, interacts with chart repositories where charts are stored, and finally installs and manages the release cycle of chats into an existing Kubernetes cluster. The installation process takes a chart, applies custom, operational environment-specific configuration and installs the chart into the Kubernetes cluster, creating a release.

Helm allows defining an application as a set of Kubernetes cluster components and provides mechanisms to manage these sets for their entire lifecycle.

Chart

Helm Glossary - Chart

A chart is a Helm package and a package format, the Kubernetes equivalent of a yum RPM file or a Homebrew formula. A chart contains all resource definitions necessary to deploy and run an application inside Kubernetes, arranged in a specific layout. A chart may be used to deploy a simple application, or a full web application stack with multiple dependencies, such as HTTP servers, database, caches and so on.

Chart Name

A chart is identified by its name in repositories. Examples: "nginx" or "postgresql". For custom charts, the name of the chart is specified in the name field of the Chart.yaml metadata file. Chart names should use lower case letter and numbers, and start with a letter. Hyphens are allowed. Uppercase letter, underscores or dots should not be used in chart names. The directory that contains a chart must have the same name as the chart. For more details see Chart Names Best Practices.

Chart Versioning

Chart.yaml carries two version fields: the chart version (version) and the application version (appVersion).

Every chart must have a SemVer 2 version specified as the version field of the Chart.yaml metadata file. Packages exposed by repositories, as well as. packages generated by helm package are identified by their name and their version. For example, the chart archive of an "nginx" package whose version filed is "1.2.3" will be named "nginx-1.2.3.tgz". Helm also uses the version number as release marker. Many other Helm tools, such as the CLI and the Tiller server use the version information. It is assumed that the version number in the chart package name matches the version field in Chart.yaml. A mismatch will cause errors. For more details on chart version see Chart Version Numbers Best Practices.

The appVersion field is intended to carry an informal application version, not necessarily SemVer 2, and is not related to the version field. This field is informational, and has no impact on chart version calculations. It is very common for the chart version and app version to be different:

NAME                               	CHART VERSION	APP VERSION	DESCRIPTION
stable/postgresql                  	6.3.2        	11.5.0     	Chart for PostgreSQL, an object-relational database manag...

Chart Archive

A chart archive is a chart in a packaged (tgz) format. The chart repositories expose chart archives. helm package creates chart archives.

Chart Installation

Charts are installed into a target Kubernetes cluster and turned into releases with helm install. The installation is an asynchronous process, the Helm client does not wait until all resources are running before it exits, this is because charts may require large Docker images that take long to install in the cluster. Without additional input, a chart will be installed with the default configuration, but custom configuration changes can be applied during the installation process.

The default option for the helm install command is to install from the default repository. However, the chart may come from other sources: a different repository, a local file, an unpacked chart directory or a URL.

Resource Installation and De-Installation Order

Template Installation and De-Installation Order

Chart Layout

This section describes a typical chart directory tree. The top level directory is the chart name, without the version information.

archaeopteryx
   |
   |- Chart.yaml
   |- values.yaml
   |- requirements.yaml
   |- requirements.lock
   |- LICENSE
   |- README.md
   |- .helmignore
   |- charts
   +- templates
         |
         |- NOTES.txt
         |- _helpers.tpl
         |- deployment.yaml
         |- service.yaml
         | ...
         +- tests

charts/ Directory

The 'charts' directory contains any charts upon which this chart depends. The content of the directory can either manually managed, or it can be updated dynamically for dependencies declared in requirements.yaml. A dependency can be either a chart archive or an unpacked chart directory. If the name of the dependency, either file or directory, starts with '_' or '.', the dependency will be ignored by the chart loader.

templates/ Directory

The templates/ Directory

Developing Custom Charts

The development of a custom chart could start with helm create, which is a command that creates a standard chart directory layout along with some common files typically used in a chart. The command provides just a basic example and is not meant to cover all Kubernetes resources. While a chart is being developed, the syntactic consistency can be checked with helm lint. Then the chart is ready for delivery, it can be packaged with helm package.

Chart Operations

• helm create
• helm lint
• helm package
• helm install
• helm inspect
• helm get manifest

Configuration

The process of installing or upgrading a chart consists in using a chart, possibly containing a hierarchy of dependencies, applying specific configuration and producing a release. This section describes where the default chart's configuration lives, how external configuration values can be provided to the installation process, how configuration is processed during installation and how the effective values surface in the release.

Default Configuration

A chart comes with default configuration specified in the values.yaml file. The content of the values.yaml file is rendered, verbatim, with:

helm inspect values <chart>

Helm_Chart_values.yaml

Overriding Default Configuration

Overriding configuration can be provided:

• on command line: Helm_install#Overriding_Default_Configuration
• in files: Helm_install#Overriding_Default_Configuration
• in environment variables

The actual configuration hierarchy can be rendered during the release with --debug.

Each piece of configuration can be referred to from templates with .Values

Values and Chart Configuration

Charts may, and usually will, expose configuration options. To see what configuration options are available for a chart use helm inspect values. Any available configuration option can be overridden by providing a YAML-formatted file during installation with the helm install -f|--values flag, or individually, on a configuration option basis, with --set.

There are five potential sources of values, where sources at the bottom of the list have higher priority and can potentially override a value specified by a source at the top of the list:

• The chart's values.yaml file
• If this is a subchart, the values.yaml file of the parent chart
• A value file supplied with helm install -f (or helm upgrade -f)
• The value passed with --set or --set-string on helm install or upgrade
• The content of a file passed with --set-file on helm install or upgrade

The effective value specified by one or more of these sources can be accessed from templates with:

 {{ .Values.fieldName }}

A value specified values.yaml can be effectively effectively eliminated, by setting that value to null with

... --set <key>=null

Accessing Configuration from Templates

Helm_Templates#Values

Dependencies

Dependencies

Hooks

TODO: https://helm.sh/docs/developing_charts/#hooks

Repository

Helm Glossary - Repository

The Chart Repository Guide

A repository is a place - usually a HTTP server - where charts are collected and shared. The charts are exposed in an archived format. A repository must expose in its root an index.yaml file that contains a list of all packages supplied by repository, together with metadata that allows retrieving and verifying those packages. When Helm is installed, it is pre-configured with a default repository. New repositories an be added. The list of locally-configured repository can be inspected with helm repo list, which essentially reads ~/.helm/repository/repositories.yaml. Repositories can be searched for charts with helm search. Because chart repositories change frequently, it is recommended to update the local cache.

Helm comes with a built-in package server for developer testing. For more details see helm serve.

Repository Name

Each locally-added repository is known under a name, which is associated with the repository URL.

Repository URL

The repository URL represents the endpoint of a Helm repository - the endpoint's root must contain an index.yaml file. Also see the discussion for the special case of dependency charts that exist on the local file system.

Default Repository

When Helm is installed, it is pre-configured to look into the official Helm Charts GitHub repository, named "stable".

Local Cache

The local repository cache is maintained under ~/.helm/repository.

TODO investigate ~/.helm/repository

Repository Operations

• helm repo
• helm search
• helm serve

Templates

Helm Templates

Release

A release is a running instance of a chart, to which a specific config was applied. Whenever a chart is installed, a new release is created. One chart can be installed multiple times into the same cluster, and each can be independently managed and upgraded. Each release has its own release name.

When a new version of a chart is released, or when the configuration of a release must be changes, the release can be upgraded with helm upgrade. Helm tries to perform the least invasive upgrade, and only upgraded things that changed since the last release. If something fails during the upgrade, a rollback can be performed with helm rollback.

Releases can be of course uninstalled, or deleted with helm delete. Helm keeps a history of deleted releases, which can be retrieved with helm list --deleted.

Release Name

If not specified, release names are generated (e.g. "happy-panda"). To specify a release name, use helm install --name. Helm keeps records of deleted releases, so a release name first used by a deleted release cannot be re-used (unless --replace is used). The release name is available in templates as a built-in object:

 {{ .Release.Name }}

Release Revision

A release version (revision) is incremental. Every time an install, upgrade or rollback happens, the revision number is incremented by 1, and the first revision is always 1. The revision numbers for a certain release can be inspected with helm history. A release revision can be used during a rollback. The release revision is available in templates as a built-in object:

 {{ .Release.Revision }}

Release Marker

The package version is included in the release marker.

Release Operations

• helm install
• helm get manifest - display the manifest content that was posted to the server as part of the installation process.
• helm list - display currently deployed releases.
• helm history
• helm status
• helm upgrade
• helm rollback
• helm delete

Runtime

The Helm Client

The Helm client is a command-line client for end users. The client is responsible for managing charts. It helps with local chart development, manages the interaction with chart repositories and interacts with the Tiller server. The interaction with the server consists in installing charts and providing a CLI for the release life cycle (the server manages the releases).

The Tiller Server

The Tiller server is an in-cluster component that interacts with the Helm client and interfaces with the Kubernetes API Server.

The server is responsible for managing releases. It does that by handling client requests, combining a chart and the configuration to build a release, installing charts and then tracking their subsequent release, then upgrading and uninstalling charts.

Tiller stores release information in ConfigMaps in the namespace where it is running. It could be configured to use a storage backend that uses Secrets for storing release information. More here. It could also be configured to use an SQL storage backend for storing release information. More here.

TODO: https://helm.sh/docs/using_helm/#tiller-namespaces-and-rbac

Security

Security Concepts

Plugins

Plugin Concepts

Tests

TODO: https://helm.sh/docs/developing_charts/#chart-tests