Using Helm

This guide explains the basics of using Helm to manage packages on yourKubernetes cluster. It assumes that you have already installed theHelm client.

If you are simply interested in running a few quick commands, you may wish tobegin with the Quickstart Guide. This chapter covers theparticulars of Helm commands, and explains how to use Helm.

Three Big Concepts

A Chart is a Helm package. It contains all of the resource definitionsnecessary to run an application, tool, or service inside of a Kubernetescluster. Think of it like the Kubernetes equivalent of a Homebrew formula, anApt dpkg, or a Yum RPM file.

A Repository is the place where charts can be collected and shared. It’s likePerl’s CPAN archive or the Fedora PackageDatabase, but for Kubernetes packages.

A Release is an instance of a chart running in a Kubernetes cluster. One chartcan often be installed many times into the same cluster. And each time it isinstalled, a new release is created. Consider a MySQL chart. If you want twodatabases running in your cluster, you can install that chart twice. Each onewill have its own release, which will in turn have its own release name.

With these concepts in mind, we can now explain Helm like this:

Helm installs charts into Kubernetes, creating a new release for eachinstallation. And to find new charts, you can search Helm chart repositories.

‘helm search’: Finding Charts

Helm comes with a powerful search command. It can be used to search two differenttypes of source:

  • helm search hub searches the Helm Hub, which compriseshelm charts from dozens of different repositories.
  • helm search repo searches the repositories that you have added to your localhelm client (with helm repo add). This search is done over local data, and nopublic network connection is needed.You can find publicly available charts by running helm search hub:
  1. $ helm search hub wordpress
  2. URL                                                   CHART VERSION    APP VERSION    DESCRIPTION
  3. https://hub.helm.sh/charts/bitnami/wordpress          7.6.7            5.2.4          Web publishing platform for building blogs and ...
  4. https://hub.helm.sh/charts/presslabs/wordpress-...    v0.6.3           v0.6.3         Presslabs WordPress Operator Helm Chart
  5. https://hub.helm.sh/charts/presslabs/wordpress-...    v0.7.1           v0.7.1         A Helm chart for deploying a WordPress site on ...

The above searches for all wordpress charts on Helm Hub.

With no filter, helm search hub shows you all of the available charts.

Using helm search repo, you can find the names of the charts in repositories you have already added:

  1. $ helm repo add brigade https://brigadecore.github.io/charts
  2. "brigade" has been added to your repositories
  3. $ helm search repo brigade
  4. NAME                            CHART VERSION    APP VERSION    DESCRIPTION
  5. brigade/brigade                 1.3.2            v1.2.1         Brigade provides event-driven scripting of Kube...
  6. brigade/brigade-github-app      0.4.1            v0.2.1         The Brigade GitHub App, an advanced gateway for...
  7. brigade/brigade-github-oauth    0.2.0            v0.20.0        The legacy OAuth GitHub Gateway for Brigade
  8. brigade/brigade-k8s-gateway     0.1.0                           A Helm chart for Kubernetes
  9. brigade/brigade-project         1.0.0            v1.0.0         Create a Brigade project
  10. brigade/kashti                  0.4.0            v0.4.0         A Helm chart for Kubernetes

Helm search uses a fuzzy string matching algorithm, so you can type parts of words or phrases:

  1. $ helm search repo kash
  2. NAME              CHART VERSION    APP VERSION    DESCRIPTION
  3. brigade/kashti    0.4.0            v0.4.0         A Helm chart for Kubernetes

Search is a good way to find available packages. Once you have found a packageyou want to install, you can use helm install to install it.

‘helm install’: Installing a Package

To install a new package, use the helm install command. At its simplest, ittakes two arguments: A release name that you pick, and the name of the chart you want to install.

  1. $ helm install happy-panda stable/mariadb
  2. Fetched stable/mariadb-0.3.0 to /Users/mattbutcher/Code/Go/src/helm.sh/helm/mariadb-0.3.0.tgz
  3. happy-panda
  4. Last Deployed: Wed Sep 28 12:32:28 2016
  5. Namespace: default
  6. Status: DEPLOYED
  8. Resources:
  9. ==> extensions/Deployment
  10. NAME                     DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
  11. happy-panda-mariadb   1         0         0            0           1s
  13. ==> v1/Secret
  14. NAME                     TYPE      DATA      AGE
  15. happy-panda-mariadb   Opaque    2         1s
  17. ==> v1/Service
  18. NAME                     CLUSTER-IP   EXTERNAL-IP   PORT(S)    AGE
  19. happy-panda-mariadb   10.0.0.70    <none>        3306/TCP   1s
  22. Notes:
  23. MariaDB can be accessed via port 3306 on the following DNS name from within your cluster:
  24. happy-panda-mariadb.default.svc.cluster.local
  26. To connect to your database run the following command:
  28.    kubectl run happy-panda-mariadb-client --rm --tty -i --image bitnami/mariadb --command -- mysql -h happy-panda-mariadb

Now the mariadb chart is installed. Note that installing a chart creates a newrelease object. The release above is named happy-panda. (If you want Helm to generatea name for you, leave off the release name and use —generate-name.)

During installation, the helm client will print useful information about whichresources were created, what the state of the release is, and also whether thereare additional configuration steps you can or should take.

Helm does not wait until all of the resources are running before it exits. Manycharts require Docker images that are over 600M in size, and may take a longtime to install into the cluster.

To keep track of a release’s state, or to re-read configuration information, youcan use helm status:

  1. $ helm status happy-panda
  2. Last Deployed: Wed Sep 28 12:32:28 2016
  3. Namespace: default
  4. Status: DEPLOYED
  6. Resources:
  7. ==> v1/Service
  8. NAME                     CLUSTER-IP   EXTERNAL-IP   PORT(S)    AGE
  9. happy-panda-mariadb   10.0.0.70    <none>        3306/TCP   4m
  11. ==> extensions/Deployment
  12. NAME                     DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
  13. happy-panda-mariadb   1         1         1            1           4m
  15. ==> v1/Secret
  16. NAME                     TYPE      DATA      AGE
  17. happy-panda-mariadb   Opaque    2         4m
  20. Notes:
  21. MariaDB can be accessed via port 3306 on the following DNS name from within your cluster:
  22. happy-panda-mariadb.default.svc.cluster.local
  24. To connect to your database run the following command:
  26.    kubectl run happy-panda-mariadb-client --rm --tty -i --image bitnami/mariadb --command -- mysql -h happy-panda-mariadb

The above shows the current state of your release.

Customizing the Chart Before Installing

Installing the way we have here will only use the default configuration optionsfor this chart. Many times, you will want to customize the chart to use yourpreferred configuration.

To see what options are configurable on a chart, use helm show values:

  1. $ helm show values stable/mariadb
  2. Fetched stable/mariadb-0.3.0.tgz to /Users/mattbutcher/Code/Go/src/helm.sh/helm/mariadb-0.3.0.tgz
  3. ## Bitnami MariaDB image version
  4. ## ref: https://hub.docker.com/r/bitnami/mariadb/tags/
  5. ##
  6. ## Default: none
  7. imageTag: 10.1.14-r3
  9. ## Specify a imagePullPolicy
  10. ## Default to 'Always' if imageTag is 'latest', else set to 'IfNotPresent'
  11. ## ref: https://kubernetes.io/docs/user-guide/images/#pre-pulling-images
  12. ##
  13. # imagePullPolicy:
  15. ## Specify password for root user
  16. ## ref: https://github.com/bitnami/bitnami-docker-mariadb/blob/master/README.md#setting-the-root-password-on-first-run
  17. ##
  18. # mariadbRootPassword:
  20. ## Create a database user
  21. ## ref: https://github.com/bitnami/bitnami-docker-mariadb/blob/master/README.md#creating-a-database-user-on-first-run
  22. ##
  23. # mariadbUser:
  24. # mariadbPassword:
  26. ## Create a database
  27. ## ref: https://github.com/bitnami/bitnami-docker-mariadb/blob/master/README.md#creating-a-database-on-first-run
  28. ##
  29. # mariadbDatabase:
  30. # ...

You can then override any of these settings in a YAML formatted file, and thenpass that file during installation.

  1. $ echo '{mariadbUser: user0, mariadbDatabase: user0db}' > config.yaml
  2. $ helm install -f config.yaml stable/mariadb

The above will create a default MariaDB user with the name user0, and grantthis user access to a newly created user0db database, but will accept all therest of the defaults for that chart.

There are two ways to pass configuration data during install:

  • —values (or -f): Specify a YAML file with overrides. This can bespecified multiple times and the rightmost file will take precedence
  • —set: Specify overrides on the command line.If both are used, —set values are merged into —values with higherprecedence. Overrides specified with —set are persisted in a ConfigMap.Values that have been —set can be viewed for a given release with helm getvalues <release-name>. Values that have been —set can be cleared by runninghelm upgrade with —reset-values specified.

The Format and Limitations of —set

The —set option takes zero or more name/value pairs. At its simplest, it isused like this: —set name=value. The YAML equivalent of that is:

  1. name: value

Multiple values are separated by , characters. So —set a=b,c=d becomes:

  1. a: b
  2. c: d

More complex expressions are supported. For example, —set outer.inner=valueis translated into this:

  1. outer:
  2.   inner: value

Lists can be expressed by enclosing values in { and }. For example, —setname={a, b, c} translates to:

  1. name:
  2.   - a
  3.   - b
  4.   - c

As of Helm 2.5.0, it is possible to access list items using an array indexsyntax. For example, —set servers[0].port=80 becomes:

  1. servers:
  2.   - port: 80

Multiple values can be set this way. The line —setservers[0].port=80,servers[0].host=example becomes:

  1. servers:
  2.   - port: 80
  3.     host: example

Sometimes you need to use special characters in your —set lines. You can usea backslash to escape the characters; —set name=value1\,value2 will become:

  1. name: "value1,value2"

Similarly, you can escape dot sequences as well, which may come in handy whencharts use the toYaml function to parse annotations, labels and nodeselectors. The syntax for —set nodeSelector."kubernetes.io/role"=masterbecomes:

  1. nodeSelector:
  2.   kubernetes.io/role: master

Deeply nested data structures can be difficult to express using —set. Chartdesigners are encouraged to consider the —set usage when designing the formatof a values.yaml file.

More Installation Methods

The helm install command can install from several sources:

  • A chart repository (as we’ve seen above)
  • A local chart archive (helm install foo-0.1.1.tgz)
  • An unpacked chart directory (helm install path/to/foo)
  • A full URL (helm install https://example.com/charts/foo-1.2.3.tgz)

‘helm upgrade’ and ‘helm rollback’: Upgrading a Release, and Recovering on Failure

When a new version of a chart is released, or when you want to change theconfiguration of your release, you can use the helm upgrade command.

An upgrade takes an existing release and upgrades it according to theinformation you provide. Because Kubernetes charts can be large and complex,Helm tries to perform the least invasive upgrade. It will only update thingsthat have changed since the last release.

  1. $ helm upgrade -f panda.yaml happy-panda stable/mariadb
  2. Fetched stable/mariadb-0.3.0.tgz to /Users/mattbutcher/Code/Go/src/helm.sh/helm/mariadb-0.3.0.tgz
  3. happy-panda has been upgraded. Happy Helming!
  4. Last Deployed: Wed Sep 28 12:47:54 2016
  5. Namespace: default
  6. Status: DEPLOYED
  7. ...

In the above case, the happy-panda release is upgraded with the same chart,but with a new YAML file:

  1. mariadbUser: user1

We can use helm get values to see whether that new setting took effect.

  1. $ helm get values happy-panda
  2. mariadbUser: user1

The helm get command is a useful tool for looking at a release in the cluster.And as we can see above, it shows that our new values from panda.yaml weredeployed to the cluster.

Now, if something does not go as planned during a release, it is easy to rollback to a previous release using helm rollback [RELEASE] [REVISION].

  1. $ helm rollback happy-panda 1

The above rolls back our happy-panda to its very first release version. Arelease version is an incremental revision. Every time an install, upgrade, orrollback happens, the revision number is incremented by 1. The first revisionnumber is always 1. And we can use helm history [RELEASE] to see revisionnumbers for a certain release.

Helpful Options for Install/Upgrade/Rollback

There are several other helpful options you can specify for customizing thebehavior of Helm during an install/upgrade/rollback. Please note that this isnot a full list of cli flags. To see a description of all flags, just run helm<command> —help.

  • —timeout: A value in seconds to wait for Kubernetes commands to completeThis defaults to 300 (5 minutes)
  • —wait: Waits until all Pods are in a ready state, PVCs are bound,Deployments have minimum (Desired minus maxUnavailable) Pods in readystate and Services have an IP address (and Ingress if a LoadBalancer) beforemarking the release as successful. It will wait for as long as the —timeoutvalue. If timeout is reached, the release will be marked as FAILED. Note: Inscenario where Deployment has replicas set to 1 and maxUnavailable is notset to 0 as part of rolling update strategy, —wait will return as ready asit has satisfied the minimum Pod in ready condition.
  • —no-hooks: This skips running hooks for the command
  • —recreate-pods (only available for upgrade and rollback): This flagwill cause all pods to be recreated (with the exception of pods belonging todeployments). (DEPRECATED in Helm 3)

‘helm uninstall’: Uninstalling a Release

When it is time to uninstall or uninstall a release from the cluster, use thehelm uninstall command:

  1. $ helm uninstall happy-panda

This will remove the release from the cluster. You can see all of your currentlydeployed releases with the helm list command:

  1. $ helm list
  2. NAME            VERSION UPDATED                         STATUS          CHART
  3. inky-cat        1       Wed Sep 28 12:59:46 2016        DEPLOYED        alpine-0.1.0

From the output above, we can see that the happy-panda release wasuninstalled.

In previous versions of Helm, when a release was deleted, a record of itsdeletion would remain. In Helm 3, deletion removes the release record as well.If you wish to keep a deletion release record, use helm uninstall —keep-history.Using helm list —uninstalled will only show releases that where uninstalledwith the —keep-history flag.

The helm list —all flag will show you all release records that Helm has retained,including records for failed or deleted items (if —keep-history was specified):

  1. $  helm list --all
  2. NAME            VERSION UPDATED                         STATUS          CHART
  3. happy-panda     2       Wed Sep 28 12:47:54 2016        UNINSTALLED     mariadb-0.3.0
  4. inky-cat        1       Wed Sep 28 12:59:46 2016        DEPLOYED        alpine-0.1.0
  5. kindred-angelf  2       Tue Sep 27 16:16:10 2016        UNINSTALLED     alpine-0.1.0

Note that because releases are now deleted by default, it is no longer possible torollback an uninstalled resource.

‘helm repo’: Working with Repositories

Helm 3 no longer ships with a default chart repository. The helm repo commandgroup provides commands to add, list, and remove repositories.

You can see which repositories are configured using helm repo list:

  1. $ helm repo list
  2. NAME            URL
  3. stable          https://kubernetes-charts.storage.googleapis.com
  4. mumoshu         https://mumoshu.github.io/charts

And new repositories can be added with helm repo add:

  1. $ helm repo add dev https://example.com/dev-charts

Because chart repositories change frequently, at any point you can make sureyour Helm client is up to date by running helm repo update.

Repositories can be removed with helm repo remove.

Creating Your Own Charts

The Chart Development Guide explains how to develop your owncharts. But you can get started quickly by using the helm create command:

  1. $ helm create deis-workflow
  2. Creating deis-workflow

Now there is a chart in ./deis-workflow. You can edit it and create your owntemplates.

As you edit your chart, you can validate that it is well-formed by runninghelm lint.

When it’s time to package the chart up for distribution, you can run the helmpackage command:

  1. $ helm package deis-workflow
  2. deis-workflow-0.1.0.tgz

And that chart can now easily be installed by helm install:

  1. $ helm install ./deis-workflow-0.1.0.tgz
  2. ...

Charts that are packaged can be loaded into chart repositories. See thedocumentation for your chart repository server to learn how to upload.

Note: The stable repository is managed on the Kubernetes Charts GitHubrepository. That project accepts chart sourcecode, and (after audit) packages those for you.

Conclusion

This chapter has covered the basic usage patterns of the helm client,including searching, installation, upgrading, and uninstalling. It has alsocovered useful utility commands like helm status, helm get, and helm repo.

For more information on these commands, take a look at Helm’s built-in help:helm help.

In the next chapter, we look at the process of developing charts.