Quickstart Guide

This guide covers how you can quickly get started using Helm.

Prerequisites

The following prerequisites are required for a successful and properly secured use of Helm.

  • A Kubernetes cluster
  • Deciding what security configurations to apply to your installation, if any
  • Installing and configuring Helm and Tiller, the cluster-side service.

Install Kubernetes or have access to a cluster

  • You must have Kubernetes installed. For the latest release of Helm, we recommend the latest stable release of Kubernetes, which in most cases is the second-latest minor release.
  • You should also have a local configured copy of kubectl.NOTE: Kubernetes versions prior to 1.6 have limited or no support for role-based access controls (RBAC).

Helm will figure out where to install Tiller by reading your Kubernetesconfiguration file (usually $HOME/.kube/config). This is the same filethat kubectl uses.

To find out which cluster Tiller would install to, you can runkubectl config current-context or kubectl cluster-info.

  1. $ kubectl config current-context
  2. my-cluster

Understand your Security Context

As with all powerful tools, ensure you are installing it correctly for your scenario.

If you're using Helm on a cluster that you completely control, like minikube or a cluster on a private network in which sharing is not a concern, the default installation — which applies no security configuration — is fine, and it's definitely the easiest. To install Helm without additional security steps, install Helm and then initialize Helm.

However, if your cluster is exposed to a larger network or if you share your cluster with others — production clusters fall into this category — you must take extra steps to secure your installation to prevent careless or malicious actors from damaging the cluster or its data. To apply configurations that secure Helm for use in production environments and other multi-tenant scenarios, see Securing a Helm installation

If your cluster has Role-Based Access Control (RBAC) enabled, you may wantto configure a service account and rules before proceeding.

Install Helm

Download a binary release of the Helm client. You can use tools likehomebrew, or look at the official releases page.

For more details, or for other options, see the installationguide.

Initialize Helm and Install Tiller

Once you have Helm ready, you can initialize the local CLI and alsoinstall Tiller into your Kubernetes cluster in one step:

  1. $ helm init --history-max 200

TIP: Setting —history-max on helm init is recommended as configmaps and other objects in helm history can grow large in number if not purged by max limit. Without a max history set the history is kept indefinitely, leaving a large number of records for helm and tiller to maintain.

This will install Tiller into the Kubernetes cluster you saw withkubectl config current-context.

TIP: Want to install into a different cluster? Use the—kube-context flag.

TIP: When you want to upgrade Tiller, just run helm init —upgrade.

By default, when Tiller is installed, it does not have authentication enabled.To learn more about configuring strong TLS authentication for Tiller, consultthe Tiller TLS guide.

Install an Example Chart

To install a chart, you can run the helm install command. Helm hasseveral ways to find and install a chart, but the easiest is to use oneof the official stable charts.

  1. $ helm repo update              # Make sure we get the latest list of charts
  2. $ helm install stable/mysql
  3. NAME:   wintering-rodent
  4. LAST DEPLOYED: Thu Oct 18 14:21:18 2018
  5. NAMESPACE: default
  6. STATUS: DEPLOYED
  7.  
  8. RESOURCES:
  9. ==> v1/Secret
  10. NAME                    AGE
  11. wintering-rodent-mysql  0s
  12.  
  13. ==> v1/ConfigMap
  14. wintering-rodent-mysql-test  0s
  15.  
  16. ==> v1/PersistentVolumeClaim
  17. wintering-rodent-mysql  0s
  18.  
  19. ==> v1/Service
  20. wintering-rodent-mysql  0s
  21.  
  22. ==> v1beta1/Deployment
  23. wintering-rodent-mysql  0s
  24.  
  25. ==> v1/Pod(related)
  26.  
  27. NAME                                    READY  STATUS   RESTARTS  AGE
  28. wintering-rodent-mysql-6986fd6fb-988x7  0/1    Pending  0         0s
  29.  
  30.  
  31. NOTES:
  32. MySQL can be accessed via port 3306 on the following DNS name from within your cluster:
  33. wintering-rodent-mysql.default.svc.cluster.local
  34.  
  35. To get your root password run:
  36.  
  37.     MYSQL_ROOT_PASSWORD=$(kubectl get secret --namespace default wintering-rodent-mysql -o jsonpath="{.data.mysql-root-password}" | base64 --decode; echo)
  38.  
  39. To connect to your database:
  40.  
  41. 1. Run an Ubuntu pod that you can use as a client:
  42.  
  43.     kubectl run -i --tty ubuntu --image=ubuntu:16.04 --restart=Never -- bash -il
  44.  
  45. 2. Install the mysql client:
  46.  
  47.     $ apt-get update && apt-get install mysql-client -y
  48.  
  49. 3. Connect using the mysql cli, then provide your password:
  50.     $ mysql -h wintering-rodent-mysql -p
  51.  
  52. To connect to your database directly from outside the K8s cluster:
  53.     MYSQL_HOST=127.0.0.1
  54.     MYSQL_PORT=3306
  55.  
  56.     # Execute the following command to route the connection:
  57.     kubectl port-forward svc/wintering-rodent-mysql 3306
  58.  
  59.     mysql -h ${MYSQL_HOST} -P${MYSQL_PORT} -u root -p${MYSQL_ROOT_PASSWORD}

In the example above, the stable/mysql chart was released, and the name ofour new release is wintering-rodent. You get a simple idea of thefeatures of this MySQL chart by running helm inspect stable/mysql.

Whenever you install a chart, a new release is created. So one chart canbe installed multiple times into the same cluster. And each can beindependently managed and upgraded.

The helm install command is a very powerful command with manycapabilities. To learn more about it, check out the Using HelmGuide

Learn About Releases

It's easy to see what has been released using Helm:

  1. $ helm ls
  2. NAME                REVISION    UPDATED                     STATUS      CHART           APP VERSION    NAMESPACE
  3. wintering-rodent    1           Thu Oct 18 15:06:58 2018    DEPLOYED    mysql-0.10.1    5.7.14         default

The helm list function will show you a list of all deployed releases.

Uninstall a Release

To uninstall a release, use the helm delete command:

  1. $ helm delete wintering-rodent
  2. release "wintering-rodent" deleted

This will uninstall wintering-rodent from Kubernetes, but you willstill be able to request information about that release:

  1. $ helm status wintering-rodent
  2. LAST DEPLOYED: Thu Oct 18 14:21:18 2018
  3. NAMESPACE: default
  4. STATUS: DELETED
  5.  
  6. NOTES:
  7. MySQL can be accessed via port 3306 on the following DNS name from within your cluster:
  8. wintering-rodent-mysql.default.svc.cluster.local
  9.  
  10. To get your root password run:
  11.  
  12.     MYSQL_ROOT_PASSWORD=$(kubectl get secret --namespace default wintering-rodent-mysql -o jsonpath="{.data.mysql-root-password}" | base64 --decode; echo)
  13.  
  14. To connect to your database:
  15.  
  16. 1. Run an Ubuntu pod that you can use as a client:
  17.  
  18.     kubectl run -i --tty ubuntu --image=ubuntu:16.04 --restart=Never -- bash -il
  19.  
  20. 2. Install the mysql client:
  21.  
  22.     $ apt-get update && apt-get install mysql-client -y
  23.  
  24. 3. Connect using the mysql cli, then provide your password:
  25.     $ mysql -h wintering-rodent-mysql -p
  26.  
  27. To connect to your database directly from outside the K8s cluster:
  28.     MYSQL_HOST=127.0.0.1
  29.     MYSQL_PORT=3306
  30.  
  31.     # Execute the following command to route the connection:
  32.     kubectl port-forward svc/wintering-rodent-mysql 3306
  33.  
  34.     mysql -h ${MYSQL_HOST} -P${MYSQL_PORT} -u root -p${MYSQL_ROOT_PASSWORD}

Because Helm tracks your releases even after you've deleted them, youcan audit a cluster's history, and even undelete a release (with helm rollback).

Reading the Help Text

To learn more about the available Helm commands, use helm help or typea command followed by the -h flag:

  1. $ helm get -h