Bookmark this page

Helm Charts

Objectives

  • Deploy and update applications from resource manifests that are packaged as Helm charts.

Helm

Helm is an open source application that helps to manage the lifecycle of Kubernetes applications.

Helm introduces the concept of charts. A chart is a package that describes a set of Kubernetes resources that you can deploy. Helm charts define values that you can customize when deploying an application. Helm includes functions to distribute charts and updates.

Many organizations distribute Helm charts to deploy applications. Often, Helm is the supported mechanism to deploy a specific application.

However, Helm does not cover all needs to manage certain kinds of applications. Operators have a more complete model that can handle the lifecycle of more complex applications. For more details about operators, refer to the section called “ Kubernetes Operators and the Operator Lifecycle Manager.

Helm Charts

A Helm chart defines Kubernetes resources that you can deploy. A chart is a collection of files with a defined structure. These files include chart metadata (such as the chart name or version), resource definitions, and supporting material.

Chart authors can use the template feature of the Go language for the resource definitions. For example, instead of specifying the image for a deployment, charts can use user-provided values for the image. By using values to choose an image, cluster administrators can replace a default public image with an image from a private repository.

The following diagram shows the structure of a minimal Helm chart:

sample/
├── Chart.yaml 1
├── templates 2
|   |── example.yaml
└── values.yaml 3

1

The Chart.yaml file contains chart metadata, such as the name and version of the chart.

2

The templates directory contains files that define application resources such as deployments.

3

The values.yaml file contains default values for the chart.

Helm charts can contain hooks that Helm executes at different points during installations and upgrades. Hooks can automate tasks for installations and upgrades. With hooks, Helm charts can manage more complex applications than purely manifest-based processes. Review the chart documentation to learn about the chart hooks and their implications.

Using Helm Charts

Helm is a command-line application. The helm command interacts with the following entities:

Charts

Charts are the packaged applications that the helm command deploys.

Releases

A release is the result of deploying a chart. You can deploy a chart many times to the same cluster. Each deployment is a different release.

Versions

A Helm chart can have many versions. Chart authors can release updates to charts, to adapt to later application versions, introduce new features, or fix issues.

You can use and refer to charts in various ways. For example, if your local file system contains a chart, then you can refer to that chart by using the path to the chart directory. You can also use a path or a URL that contains a chart that is packaged in a tar archive with gzip compression.

Inspecting Helm Charts

Use the helm show command to display information about a chart. The show chart subcommand displays general information, such as the maintainers, or the source URL.

[user@host ~]$ helm show chart chart-reference
apiVersion: v1
description: A Helm chart for Kubernetes
name: examplechart
version: 0.1.0
maintainers:
- email: dev@example.com
  name: Developer
sources:
- https://git.example.com/examplechart

The show values subcommand displays the default values for the chart. The output is in YAML format and comes from the values.yaml file in the chart.

[user@host ~]$ helm show values chart-reference
image:
  repository: "sample"
  tag: "1.8.10"
  pullPolicy: IfNotPresent
...output omitted...

Chart resources use the values from the values.yaml file by default. You can override these default values. You can use the output of the show values command to discover customizable values.

Installing Helm Charts

After inspecting the chart, you can deploy the resources in the chart by using the helm install command. In Helm, install refers to deploying the resources in a chart to create a release.

Always refer to the documentation of the chart before installation to learn about prerequisites, extra installation steps, and other information.

To install a chart, you must decide on the following parameters:

  • The deployment target namespace

  • The values to override

  • The release name

Helm charts can contain Kubernetes resources of any kind. These resources can be namespaced or non-namespaced. Like normal resource definitions, namespaced resources in charts can define or omit a namespace declaration.

Most Helm charts that deploy applications do not create a namespace, and namespaced resources in the chart omit a namespace declaration. Typically, when deploying a chart that follows this structure, you create a namespace for the deployment, and Helm creates namespaced resources in this namespace.

After deciding the target namespace, you can design the values to use. Inspect the documentation and the output of the helm show values command to decide which values to override.

You can define values by writing a YAML file that contains them. This file can follow the structure from the output of the helm show values command, which contains the default values. Specify only the values to override.

Consider the following output from the helm show values command for an example chart:

image:
  repository: "sample"
  tag: "1.8.10"
  pullPolicy: IfNotPresent

Create a values.yaml file without the image key if you do not want to override any image parameters. Omit the pullPolicy key to override the tag key but not the pull policy. For example, the following YAML file would override only the image tag:

image:
  tag: "1.8.10-patched"

Besides the YAML file, you can override specific values by using command-line arguments.

The final element to prepare a chart deployment is choosing a release name. You can deploy a chart many times to a cluster. Each chart deployment must have a unique release name for identification purposes. Many Helm charts use the release name to construct the name of the created resources.

With the namespace, values, and release name, you can start the deployment process. The helm install command creates a release in a namespace, with a set of values.

Rendering Manifests from a Chart

You can use the --dry-run option to preview the effects of installing a chart.

[user@host ~]$ helm install release-name chart-reference  --dry-run \
  --values values.yaml
NAME: release-name 1
LAST DEPLOYED: Tue May 30 13:14:57 2023
NAMESPACE: current-namespace
STATUS: pending-install
REVISION: 1
TEST SUITE: None
HOOKS:
MANIFEST:
---
# Source: chart/templates/serviceaccount.yaml 2
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-release-sa
  labels:
...output omitted...

NOTES: 3
The application can be accessed via port 1234.
...output omitted...

1

General information about the new release

2

A list of the resources that the helm install command would create

3

Additional information

Note

You define values to use for the installation with the --values values.yaml option. In this file, you override the default values from the chart that are defined in the values.yaml file that the chart contains.

Often, chart resource names include the release name. In the example output of the helm install command, the service account is a combination of the release name and the -sa text.

Chart authors can provide installation notes that use the chart values. In the same example, the port number in the notes reflects a value from the values.yaml file.

If the preview looks correct, then you can run the same command without the --dry-run option to deploy the resources and create the release.

Releases

When the helm install command runs successfully, besides creating the resources, Helm creates a release. Helm stores information about the release as a secret of the helm.sh/release.v1 type.

Inspecting Releases

Use the helm list command to inspect releases on a cluster.

[user@host ~]$ helm list
NAME         NAMESPACE   REVISION  ...  STATUS     CHART            APP VERSION
my-release   example     1         ...  deployed   example-4.12.1   1.8.10

Similarly to kubectl commands, many helm commands have the --all-namespaces and --namespace options. The helm list command without options lists releases in the current namespace. If you use the --all-namespaces option, then it lists releases in all namespaces. If you use the --namespace option, then it lists releases in a single namespace.

Warning

Do not manipulate the release secret. If you remove the secret, then Helm cannot operate with the release.

Upgrading Releases

The helm upgrade command can apply changes to existing releases, such as updating values or the chart version.

Important

By default, this command automatically updates releases to use the latest version of the chart.

The helm upgrade command uses similar arguments and options to the helm install command. However, the helm upgrade command interacts with existing resources in the cluster instead of creating resources from a blank state. Therefore, the helm upgrade command can have more complex effects, such as conflicting changes. Always review the chart documentation when using a later version of a chart, and when changing values. You can use the --dry-run option to preview the manifests that the helm upgrade command uses, and compare them to the running resources.

Rolling Back Helm Upgrades

Helm keeps a log of release upgrades, to review changes and roll back to previous releases.

You can review this log by using the helm history command:

[user@host ~]$ helm history release_name
REVISION  UPDATED        STATUS      CHART        APP VERSION  DESCRIPTION
1         Wed May 31...  superseded  chart-0.0.6  latest       Install complete
2         Wed May 31...  deployed    chart-0.0.7  latest       Upgrade complete

You can use the helm rollback command to revert to an earlier revision:

[user@host ~]$ helm rollback release_name revision
Rollback was a success! Happy Helming!

Rolling back can have greater implications than upgrading, because upgrades might not be reversible. If you keep a test environment with the same upgrades as a production environment, then you can test rollbacks before performing them in the production environment to find potential issues.

Helm Repositories

Charts can be distributed as files, archives, or container images, or by using chart repositories.

The helm repo command provides the following subcommands to work with chart repositories.

SubcommandDescription
add NAME REPOSITORY_URL Add a Helm chart repository.
list List Helm chart repositories.
update Update Helm chart repositories.
remove REPOSITORY1_NAME REPOSITORY2_NAME …​ Remove Helm chart repositories.

The following command adds a repository:

[user@host ~]$ helm repo add \
  openshift-helm-charts https://charts.openshift.io/
"openshift-helm-charts" has been added to your repositories

This command and other repository commands change only local configuration, and do not affect any cluster resources. The helm repo add command updates the ~/.config/helm/repositories.yaml configuration file, which keeps the list of configured repositories.

When repositories are configured, other commands can use the list of repositories to perform actions. For example, the helm search repo command lists all available charts in the configured repositories:

[user@host ~]$ helm search repo
NAME          CHART VERSION    APP VERSION    DESCRIPTION
repo/chart    0.0.7            latest         A sample chart
...output omitted...

By default, the helm search repo command shows only the latest version of a chart. Use the --versions option to list all available versions. By default, the install and upgrade commands use the latest version of the chart in the repository. You can use the --version option to install specific versions.

Revision: do280-4.14-08d11e1