To the reader
For a complete example, see Helm Complete Combat
Helm
This guide describes the basics of using Helm to manage packages on a Kubernetes cluster. Until then, assume that you have installed the Helm client.
If you’re only interested in running some quick commands, start with the Quick Start guide. This chapter contains a detailed explanation of the Helm command and explains how to use it.
The three concepts
Chart represents the Helm package. It contains all resource definitions needed to run applications, tools, or services within the Kubernetes cluster. You can think of it as the equivalent of Homebrew formula, Apt DPKG, or Yum RPM in Kubernetes.
A Repository is a place to store and share charts. It’s like Perl’s CPAN archive network or Fedora’s package repository, only it’s for Kubernetes packages.
Release is an instance of Chart running in a Kubernetes cluster. A chart can usually be installed multiple times in the same cluster. Each installation creates a new release. Take MySQL Chart for example. If you want to run two databases in your cluster, you can install the chart twice. Each database will have its own release and release name.
With these concepts in mind, we can explain Helm as follows:
Helm installs charts into the Kubernetes cluster and creates a new release with each installation. You can find new Chart repositories in Chart Repositories at Helm.
‘Helm Search’ : Find Charts
Helm comes with a powerful search command that can be used to search from two sources:
helm search hub从 Artifact HubHelm Charts is found and listed in. Artifact Hub houses a number of different repositories.helm search repoFrom what you add (usehelm repo add) to the repository in the local HELM client. This command searches based on local data and does not require Internet connection.
You can find publicly available charts by running the helm Search hub command:
$helm search hub wordpress URL CHART VERSION APP VERSION 7.6.7 DESCRIPTION https://hub.helm.sh/charts/bitnami/wordpress 5.2.4 Web Publishing Platform for Building blogs and... https://hub.helm.sh/charts/presslabs/wordpress-... V0.6.3 v0.6.3 Presslabs WordPress Operator Helm Chart https://hub.helm.sh/charts/presslabs/wordpress-... V0.7.1 V0.7.1 A Helm Chart for Debug A WordPress site on...Copy the codeThe above command searches all wordpress charts from Artifact Hub.
Without filtering, the Helm Search Hub command displays all available charts.
Using the helm Search repo command, you can look up the chart name from the repository you have added.
$ helm repo add brigade https://brigadecore.github.io/charts "brigade" has been added to your repositories $ helm search Repo Brigade NAME CHART VERSION APP VERSION DESCRIPTION Brigade/Brigade 1.3.2v1.2.1 Brigade provides event-driven scripting of Kube... Brigade/brigad-github -app 0.4.1v0.2.1 The Brigade Github app, an advanced gateway for... Brigade /brigade-github-oauth 0.2.0 v0.20.0 The Legacy oauth Github Gateway for Brigade brigade/ brigade-k8S-gateway 0.1.0 A Helm chart for Kubernetes Brigade/brigade-Project 1.0.0v1.0.0 Create A brigade Project brigade/ Kashti 0.4.0v0.4.0a Helm chart for KubernetesCopy the codeHelm search uses a fuzzy string matching algorithm, so you can enter only part of the name:
$helm Search repo Kash NAME CHART VERSION APP VERSION DESCRIPTION Brigade/Kashti 0.4.0 v0.4.0 A Helm CHART for KubernetesCopy the codeSearching is a good way to find available packages. Once you have found the Helm package you want to install, you can install it by using the helm install command.
‘helm install’ : Installs a helm package
Use the helm install command to install a new HELM package. The easiest way to use it is to pass in just two parameters: the release name you name and the name of the chart you want to install.
$ helm install happy-panda bitnami/wordpress
NAME: happy-panda
LAST DEPLOYED: Tue Jan 26 10:27:17 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
** Please be patient while the chart is being deployed **
Your WordPress site can be accessed through the following DNS name from within your cluster:
happy-panda-wordpress.default.svc.cluster.local (port 80)
To access your WordPress site from outside the cluster follow the steps below:
1\. Get the WordPress URL by running these commands:
NOTE: It may take a few minutes for the LoadBalancer IP to be available.
Watch the status with: 'kubectl get svc --namespace default -w happy-panda-wordpress'
export SERVICE_IP=$(kubectl get svc --namespace default happy-panda-wordpress --template "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}")
echo "WordPress URL: http://$SERVICE_IP/"
echo "WordPress Admin URL: http://$SERVICE_IP/admin"
2\. Open a browser and access WordPress using the obtained URL.
3\. Login with the following credentials below to see your blog:
echo Username: user
echo Password: $(kubectl get secret --namespace default happy-panda-wordpress -o jsonpath="{.data.wordpress-password}" | base64 --decode)
Copy the codeNow the wordpress chart is installed. Note that installing a chart creates a new release object. The release above is named happy-panda. (If you want Helm to generate a name for you, leave off the release name and use --generate-name.)
During installation, the Helm client prints useful information, including which resources have been created, the current state of release, and whether you need to perform additional configuration steps.
The Helm client does not exit until all resources are running. Many charts require Docker images over 600M in size and can take a long time to install into a cluster.
You can use helm Status to track release status, or re-read configuration information:
$ helm status happy-panda
NAME: happy-panda
LAST DEPLOYED: Tue Jan 26 10:27:17 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
** Please be patient while the chart is being deployed **
Your WordPress site can be accessed through the following DNS name from within your cluster:
happy-panda-wordpress.default.svc.cluster.local (port 80)
To access your WordPress site from outside the cluster follow the steps below:
1\. Get the WordPress URL by running these commands:
NOTE: It may take a few minutes for the LoadBalancer IP to be available.
Watch the status with: 'kubectl get svc --namespace default -w happy-panda-wordpress'
export SERVICE_IP=$(kubectl get svc --namespace default happy-panda-wordpress --template "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}")
echo "WordPress URL: http://$SERVICE_IP/"
echo "WordPress Admin URL: http://$SERVICE_IP/admin"
2\. Open a browser and access WordPress using the obtained URL.
3\. Login with the following credentials below to see your blog:
echo Username: user
echo Password: $(kubectl get secret --namespace default happy-panda-wordpress -o jsonpath="{.data.wordpress-password}" | base64 --decode)
Copy the codeThis information shows the current state of release.
Customize chart before installation
The above installation only uses chart’s default configuration options. Many times, we need to customize chart to specify the configuration we want.
Using helm Show Values you can see the configurable options in the chart:
$ helm show values bitnami/wordpress ## Global Docker image parameters ## Please, note that this will override the image parameters, including dependencies, configured to use the global value ## Current available global Docker image parameters: imageRegistry and imagePullSecrets ## # global: # imageRegistry: myRegistryName # imagePullSecrets: # - myRegistryKeySecretName # storageClass: myStorageClass ## Bitnami WordPress image version ## ref: https://hub.docker.com/r/bitnami/wordpress/tags/ ## image: registry: docker.io repository: bitnami/wordpress tag: 5.6.0 - debian - 10 - r35 [..]Copy the codeYou can then override any of the above configuration items with a YAML format file and use that file during the installation process.
$ echo '{mariadb.auth.database: user0db, mariadb.auth.username: user0}' > values.yaml
$ helm install -f values.yaml bitnami/wordpress --generate-name
Copy the codeThe above command creates a default user named user0 for MariaDB and grants the user access to the newly created user0DB database. The other default configurations in chart remain unchanged.
There are two ways to pass configuration data during installation:
--values(or-f) : Use YAML files to overwrite the configuration. You can specify multiple times, with the right-most file preferred.--set: Overwrites the specified item through the command line interface.
If both methods are used, the values in –set are merged into –values, but the values in –set have higher precedence. Overrides in –set are saved in ConfigMap. You can see the value set in the specified release by helm get values
. You can also clear the values set in –set by running helm Upgrade and specifying the –reset-values field.
--setFormat and limitations
The –set option uses 0 or more name/value pairs. The simplest usage is something like: –set name=value, equivalent to the following YAML format:
name: value
Copy the codeMultiple values are separated by commas, so the YAML representation for –set a=b,c=d is:
a: b
c: d
Copy the codeSupport for more complex expressions. For example, –set outer. Inner =value is converted to:
outer:
inner: value
Copy the codeLists are represented with curly braces ({}). For example, –set name={a, b, c} is converted to:
name:
- a
- b
- c
Copy the codeAs of version 2.5.0, you can use the syntax of array subscripts to access elements in a list. For example –set Servers [0]. Port =80
servers:
- port: 80
Copy the codeMultiple values can also be set in this way. — Set Servers [0]. Port =80, Servers [0]. Host =example
servers:
- port: 80
host: example
Copy the codeIf you need special characters in –set, you can use backslashes to escape; –set name=value1\,value2
name: "value1,value2"
Copy the codeSimilarly, you can escape sequences of points (English periods). This might come in handy when chart uses the toYaml function to resolve Annotations, Labels, and node selectors. –set nodeSelector.”kubernetes\. IO /role”=master
nodeSelector:
kubernetes.io/role: master
Copy the codeDeeply nested data structures can be difficult to express with –set. We expect Chart designers to consider the use of –set when designing the format of values. Yaml files. (See the Values file for more information.)
More Installation Methods
The helm install command can be installed from multiple sources:
- Chart’s warehouse (as described above)
- Local Chart package (
Helm install foo foo - while TGZ) - Unzipped chart directory (
helm install foo path/to/foo) - The full URL (
Helm install foo at https://example.com/charts/foo-1.2.3.tgz)
‘Helm Upgrade’ and ‘Helm rollback’ : Upgrade release and recovery on failure
When you want to upgrade to a new version of Chart or modify the release configuration, you can use the helm upgrade command.
An upgrade takes an existing release and upgrades it based on the information you provide. Since Kubernetes’ Chart can be large and complex, Helm tries to perform minimally invasive upgrades. That is, it only updates what has changed since the last release.
$ helm upgrade -f panda.yaml happy-panda bitnami/wordpress
Copy the codeIn the example above, happy-Panda release is upgraded using the same chart, but with a new YAML file:
mariadb.auth.username: user1
Copy the codeWe can use the helm get values command to see if the configuration values actually take effect:
$ helm get values happy-panda
mariadb:
auth:
username: user1
Copy the codeHelm GET is a useful tool for viewing releases in a cluster. As we saw above, the new values in Panda.yaml have been deployed to the cluster.
Now, if something happens during a RELEASE that does not meet expectations, it is easy to rollback to the previous RELEASE with the helm rollback [RELEASE] [REVISION] command.
$ helm rollback happy-panda 1
Copy the codeThis command rolls back our Happy-Panda to its original version. A Release is actually an incremental revision. Each time an install, upgrade, or rollback occurs, the value of Revision increases by 1. The value of the first revision is always 1. We can use the helm History [RELEASE] command to see the revised version number for a particular RELEASE.
Useful options for installation, upgrade, and rollback
You can also specify a few other useful options to customize the Helm’s behavior during installation, upgrade, and rollback. Note that this is not a complete list of CLI parameters. To see a description of all the parameters, run helm
--timeoutA:Go durationType to indicate the timeout to wait for the Kubernetes command to complete. The default value is5m0s.--wait: indicates that all Pods must be ready, PVC must be bound, and Deployments must have at least the minimum number of Pods in the ready state (DesiredMinus themaxUnavailable), and the Services all have IP addresses (if yesLoadBalancer, is Ingress), the release will be marked as successful. Maximum waiting time by--timeoutThe value specified. If the timeout has been reached, release will be marked asFAILED. Note: when deployedreplicasIs set to 1, but is in its rolling upgrade policymaxUnavailableWhen not set to 0,--waitWill return ready because the minimum number of Ready pods has been met.--no-hooks: A hook that does not run the current command.--recreate-pods(Applicable onlyupgrade和rollback) : This parameter causes all the PODS (except the Pod in deployment) to be rebuilt. (Deprecated at Helm 3)
‘helm uninstall’ : uninstall release
Uninstall a release from the cluster using the helm uninstall command:
$ helm uninstall happy-panda
Copy the codeThis command removes the specified release from the cluster. You can see all releases of the current deployment using the helm list command:
$HELM List NAME VERSION UPDATED STATUS CHART INky-CAT 1 Wed Sep 28 12:59:46 2016 DEPLOYED Alpine-0.1.0Copy the codeFrom the output above, we can see that happy-panda has been uninstalled.
In the previous Helm release, when a release was dropped, a deletion record was kept. In Helm 3, deleting also removes the release record. If you want to keep delete records, use helm uninstall –keep-history. Using helm list –uninstalled only shows releases deleted using –keep-history.
Helm list –all displays all release records kept by helm, including failed or deleted entries (–keep-history is specified) :
$ helm list --all NAME VERSION UPDATED STATUS CHART happy-panda 2 Wed Sep 28 12:47:54 2016 UNINSTALLED WordPress-10.4.5.6.0 INKy-CAT 1 Wed Sep 28 12:59:46 2016 DEPLOYED Alpine-0.1.0 Kindred - Angelf 2 Tue Sep 27 16:16:10 2016 UNINSTALLED alpine - 0.1.0 fromCopy the codeNote that since release is now removed by default, you can no longer roll back a resource that has been unloaded.
‘Helm Repo’ : Use warehouse
Helm 3 no longer ships with a default Chart repository. The Helm Repo provides a set of commands to add, list, and remove warehouses.
Use the Helm Repo List to view the configured repository:
$ helm repo list
NAME URL
stable https://charts.helm.sh/stable
mumoshu https://mumoshu.github.io/charts
Copy the codeUse helm Repo add to add a new repository:
$ helm repo add dev https://example.com/dev-charts
Copy the codeBecause the Chart repository is constantly changing, you can ensure that your HELM client is up to date at any time by executing the Helm repo update command.
Use the Helm repo remove command to remove the warehouse.
Create your own charts
The Chart Development Guide describes how to develop your own chart. But you can also get started quickly by using the helm create command:
$ helm create deis-workflow
Creating deis-workflow
Copy the codeThere is now a chart in the./ deIS-Workflow directory. You can edit it and create your own template.
When you edit chart, you can verify that the format is correct with helm Lint.
When ready to package chart for distribution, you can run the helm Package command:
$helm Package DeIS-Workflow DeIS-workflow 0.1.0.tgzCopy the codeThe chart can then be easily installed using the helm install command:
$helm install deis-workflow./deis-workflow-0.1.0.tgz...Copy the codeThe packaged CHART can be uploaded to the Chart warehouse. See the Helm Chart repository for more information.
conclusion
This chapter describes the basic usage of the Helm client, including searching, installing, upgrading, and uninstalling. It also covers some useful tool-like commands, such as Helm Status, Helm GET, and helm repo.
For more information about these commands, see Helm’s built-in help command: Helm help.
In the next chapter, we’ll look at how to develop Charts.