Helm Concepts
Internal
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 the underlying applications 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
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. A chart can be unpackaged, in which case it is a folder with files that follow the Helm chart rules and conventions. A chart can also be packaged, as a tar.gz chart archive.
Chart Name
A chart is identified by its name in repositories. Examples: "nginx" or "postgresql". The chart name is sometimes referred to as chart reference. The name is part of the package identification, along with chart version. The name of the chart is also 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 in 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 tools rely on the version section of the chart archive file name as release marker. The system assumes that the version number in the chart package name matches the version number in the Chart.yaml. Failure to meet this assumption will cause an error. 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 independent from 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. The helm package command creates chart archives.
Chart Type
The type designates a chart as 'application' or 'library'. 'application' is the default type. A 'library' or 'helper' chart provides utilities or functions for the chart builder, it has no resource object and therefore is not installable. Example: https://github.com/helm/charts/tree/master/incubator/common. An application chart can be used as a library chart. This is enabled by setting the type to 'library'. The chart will then be rendered as a library chart where all utilities and functions can be leveraged. No resource objects contained by the chart will be rendered.
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 need large container 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
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 ├─ 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 Chart.yaml for Helm 3 or requirements.yaml for Helm 2. 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. For more details on dependencies see:
templates/ Directory
Developing Custom Charts
The development of a custom chart could start with the helm create command, 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 the helm lint command. Then the chart is ready for delivery, it can be packaged with helm package.
Chart Operations
Configuration
Dependencies
Repository
Templates
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
Tiller has been removed in Helm 3.
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.
Hooks
Security
Plugins
Tests
Labels
Most charts configure the Kubernetes resources created by them to carry a "release" label, whose value is the release name. This convention could be useful in providing a mechanism to identify these resources using label selectors.