mirror of https://github.com/helm/helm
parent
3437e5d6e5
commit
7d8b5bbb49
@ -0,0 +1,122 @@
|
||||
# Installing Helm
|
||||
|
||||
There are two parts to Helm: The Helm client (`helm`) and the Helm
|
||||
server (Tiller). This guide shows how to install the client, and then
|
||||
proceeds to show two ways to install the server.
|
||||
|
||||
## Installing the Helm Client
|
||||
|
||||
The Helm client can be installed either from source, or from pre-built binary
|
||||
releases.
|
||||
|
||||
### From the GitHub Releases
|
||||
|
||||
Every [release](https://github.com/kubernetes/helm/releases) of Helm
|
||||
provides binary releases for a variety of OSes. These binary versions
|
||||
can be manually downloaded and installed.
|
||||
|
||||
1. Download your [desired version](https://github.com/kubernetes/helm/releases)
|
||||
2. Unpack it (`tar -zxvf helm-v2.0.0-linux-amd64.tgz`)
|
||||
3. Find the `helm` binary in the unpacked directory, and move it to its
|
||||
desired destination (`mv linux-amd64/helm /usr/local/bin/helm`)
|
||||
|
||||
From there, you should be able to run the client: `helm help`.
|
||||
|
||||
### From Homebrew (Mac OSX)
|
||||
|
||||
Members of the Kubernetes community have contributed a Helm cask built to
|
||||
Homebrew. This formula is generally up to date.
|
||||
|
||||
```
|
||||
brew cask install helm
|
||||
```
|
||||
|
||||
(Note: There is also a formula for emacs-helm, which is a different
|
||||
project.)
|
||||
|
||||
### From Source (Linux, Mac OSX)
|
||||
|
||||
Building Helm from source is slightly more work, but is the best way to
|
||||
go if you want to test the latest (pre-release) Helm version.
|
||||
|
||||
You must have a working Go environment.
|
||||
|
||||
```console
|
||||
$ cd $GOPATH
|
||||
$ mkdir -p src/k8s.io
|
||||
$ cd src/k8s.io
|
||||
$ git clone https://github.com/kubernetes/helm.git
|
||||
$ cd helm
|
||||
$ make bootstrap build
|
||||
```
|
||||
|
||||
The `bootstrap` target will attempt to install dependencies, rebuild the
|
||||
`vendor/` tree, and validate configuration.
|
||||
|
||||
The `build` target will compile `helm` and place it in `bin/helm`.
|
||||
Tiller is also compiled, and is placed in `bin/tiller`.
|
||||
|
||||
## Installing Tiller
|
||||
|
||||
Tiller, the server portion of Helm, typically runs inside of your
|
||||
Kubernetes cluster. But for development, it can also be run locally, and
|
||||
configured to talk to a remote Kubernetes cluster.
|
||||
|
||||
### Easy In-Cluster Installation
|
||||
|
||||
The easiest way to install `tiller` into the cluster is simply to run
|
||||
`helm init`. This will validate that `helm`'s local environment is set
|
||||
up correctly (and set it up if necessary). Then it will connect to
|
||||
whatever cluster `kubectl` connects to by default (`kubectl config
|
||||
view`). Once it connects, it will install `tiller` into the
|
||||
`kube-system` namespace.
|
||||
|
||||
After `helm init`, you should be able to run `kubectl get po --namespace
|
||||
kube-system` and see Tiller running.
|
||||
|
||||
Once Tiller is installed, running `helm version` should show you both
|
||||
the client and server version. (If it shows only the client version,
|
||||
`helm` cannot yet connect to the server. Use `kubectl` to see if any
|
||||
`tiller` pods are running.)
|
||||
|
||||
### Running Tiller Locally
|
||||
|
||||
For development, it is sometimes easier to work on Tiller locally, and
|
||||
configure it to connect to a remote Kubernetes cluster.
|
||||
|
||||
The process of building Tiller is explained above.
|
||||
|
||||
Once `tiller` has been built, simply start it:
|
||||
|
||||
```console
|
||||
$ bin/tiller
|
||||
Tiller running on :44134
|
||||
```
|
||||
|
||||
When Tiller is running locally, it will attempt to connect to the
|
||||
Kubernetes cluster that is configured by `kubectl`. (Run `kubectl config
|
||||
view` to see which cluster that is.)
|
||||
|
||||
You must tell `helm` to connect to this new local Tiller host instead of
|
||||
connecting to the one in-cluster. There are two ways to do this. The
|
||||
first is to specify the `--host` option on the command line. The second
|
||||
is to set the `$HELM_HOST` environment variable.
|
||||
|
||||
```console
|
||||
$ export HELM_HOST=localhost:44134
|
||||
$ helm version # Should connect to localhost.
|
||||
Client: &version.Version{SemVer:"v2.0.0-alpha.4", GitCommit:"db...", GitTreeState:"dirty"}
|
||||
Server: &version.Version{SemVer:"v2.0.0-alpha.4", GitCommit:"a5...", GitTreeState:"dirty"}
|
||||
```
|
||||
|
||||
Importantly, even when running locally, Tiller will store release
|
||||
configuration in ConfigMaps inside of Kubernetes.
|
||||
|
||||
## Conclusion
|
||||
|
||||
In most cases, installation is as simple as getting a pre-built `helm` binary
|
||||
and running `helm init`. This document covers additional cases for those
|
||||
who want to do more sophisticated things with Helm.
|
||||
|
||||
Once you have the Helm Client and Tiller successfully installed, you can
|
||||
move on to using Helm to manage charts.
|
@ -0,0 +1,392 @@
|
||||
# Using Helm
|
||||
|
||||
This guide explains the basics of using Helm (and Tiller) to manage
|
||||
packages on your Kubernetes cluster. It assumes that you have already
|
||||
[installed](install.md) the Helm client and the Tiller server (typically by `helm
|
||||
init`).
|
||||
|
||||
If you are simply interested in running a few quick commands, you may
|
||||
wish to begin with the [Quickstart Guide](quickstart.md). This chapter
|
||||
covers the particulars of Helm commands, and explains how to use Helm.
|
||||
|
||||
## Three Big Concepts
|
||||
|
||||
A *Chart* is a Helm package. It contains all of the resource definitions
|
||||
necessary to run an application, tool, or service inside of a Kubernetes
|
||||
cluster. Think of it like a Homebrew formula or an `apt` or `rpm`
|
||||
package for Kubernetes.
|
||||
|
||||
A *Repository* is the place where charts can be collected and shared.
|
||||
It's like `npm` for Kubernetes packages.
|
||||
|
||||
A *Release* is an instance of a chart running in a Kubernetes cluster.
|
||||
One chart can often be installed many times into the same cluster. And
|
||||
each time it is installed, a new _release_ is created. Consider a MySQL
|
||||
chart. If you want two databases running in your cluster, you can
|
||||
install that chart twice. Each one will 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
|
||||
each installation. And to find new charts, you can search Helm chart
|
||||
_repositories_.
|
||||
|
||||
## 'helm search': Finding Charts
|
||||
|
||||
When you first install Helm, it is preconfigured to talk to the official
|
||||
Kubernetes charts repository. This repository contains a number of
|
||||
carefully currated and maintained charts. This chart repository is named
|
||||
`stable` by default.
|
||||
|
||||
You can see which charts are available by running `helm search`:
|
||||
|
||||
```
|
||||
$ helm search
|
||||
stable/drupal
|
||||
stable/jenkins
|
||||
stable/mariadb
|
||||
...
|
||||
```
|
||||
|
||||
With no filter, `helm search` shows you all of the available charts. You
|
||||
can narrow down your results by searching with a filter:
|
||||
|
||||
```
|
||||
$ helm search mysql
|
||||
stable/mysql
|
||||
stable/mariadb
|
||||
```
|
||||
|
||||
Now you will only see the results that match your filter. Why is
|
||||
`mariadb` in the list? Because its package description. We can use `helm
|
||||
inspect chart` to see this:
|
||||
|
||||
```
|
||||
$ helm inspect stable/mariadb
|
||||
Fetched stable/mariadb-0.3.0.tgz to /Users/mattbutcher/Code/Go/src/k8s.io/helm/mariadb-0.3.0.tgz
|
||||
description: Chart for MariaDB
|
||||
engine: gotpl
|
||||
home: https://mariadb.org
|
||||
keywords:
|
||||
- mariadb
|
||||
- mysql
|
||||
- database
|
||||
- sql
|
||||
maintainers:
|
||||
- email: containers@bitnami.com
|
||||
name: Bitnami
|
||||
name: mariadb
|
||||
sources:
|
||||
- https://github.com/bitnami/bitnami-docker-mariadb
|
||||
version: 0.3.0
|
||||
```
|
||||
|
||||
Search is a good way to find available packages. Once you have found a
|
||||
package you 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, it takes only one argument: The name of the chart.
|
||||
|
||||
```
|
||||
$ helm install stable/mariadb
|
||||
Fetched stable/mariadb-0.3.0 to /Users/mattbutcher/Code/Go/src/k8s.io/helm/mariadb-0.3.0.tgz
|
||||
happy-panda
|
||||
Last Deployed: Wed Sep 28 12:32:28 2016
|
||||
Namespace: default
|
||||
Status: DEPLOYED
|
||||
|
||||
Resources:
|
||||
==> extensions/Deployment
|
||||
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
|
||||
happy-panda-mariadb 1 0 0 0 1s
|
||||
|
||||
==> v1/Secret
|
||||
NAME TYPE DATA AGE
|
||||
happy-panda-mariadb Opaque 2 1s
|
||||
|
||||
==> v1/Service
|
||||
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
happy-panda-mariadb 10.0.0.70 <none> 3306/TCP 1s
|
||||
|
||||
|
||||
Notes:
|
||||
MariaDB can be accessed via port 3306 on the following DNS name from within your cluster:
|
||||
happy-panda-mariadb.default.svc.cluster.local
|
||||
|
||||
To connect to your database run the following command:
|
||||
|
||||
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 new _release_ object. The release above is named
|
||||
`happy-panda`. (If you want to use your own release name, simply use the
|
||||
`--name` flag on `helm install`.)
|
||||
|
||||
During installation, the `helm` client will print useful information
|
||||
about which resources were created, what the state of the release is,
|
||||
and also whether there are additional configuration steps you can or
|
||||
should take.
|
||||
|
||||
Helm does not wait until all of the resources are running before it
|
||||
exits. Many charts require Docker images that are over 600M in size, and
|
||||
may take a long time to install into the cluster.
|
||||
|
||||
To keep track of a release's state, or to re-read configuration
|
||||
information, you can use `helm status`:
|
||||
|
||||
```
|
||||
$ helm status happy-panda
|
||||
Last Deployed: Wed Sep 28 12:32:28 2016
|
||||
Namespace: default
|
||||
Status: DEPLOYED
|
||||
|
||||
Resources:
|
||||
==> v1/Service
|
||||
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
happy-panda-mariadb 10.0.0.70 <none> 3306/TCP 4m
|
||||
|
||||
==> extensions/Deployment
|
||||
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
|
||||
happy-panda-mariadb 1 1 1 1 4m
|
||||
|
||||
==> v1/Secret
|
||||
NAME TYPE DATA AGE
|
||||
happy-panda-mariadb Opaque 2 4m
|
||||
|
||||
|
||||
Notes:
|
||||
MariaDB can be accessed via port 3306 on the following DNS name from within your cluster:
|
||||
happy-panda-mariadb.default.svc.cluster.local
|
||||
|
||||
To connect to your database run the following command:
|
||||
|
||||
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
|
||||
options for this chart. Many times, you will want to customize the chart
|
||||
to use your preferred configuration.
|
||||
|
||||
To see what options are configurable on a chart, use `helm inspect
|
||||
values`:
|
||||
|
||||
```console
|
||||
helm inspect values stable/mariadb-0.3.0.tgz
|
||||
Fetched stable/mariadb-0.3.0.tgz to /Users/mattbutcher/Code/Go/src/k8s.io/helm/mariadb-0.3.0.tgz
|
||||
## Bitnami MariaDB image version
|
||||
## ref: https://hub.docker.com/r/bitnami/mariadb/tags/
|
||||
##
|
||||
## Default: none
|
||||
imageTag: 10.1.14-r3
|
||||
|
||||
## Specify a imagePullPolicy
|
||||
## Default to 'Always' if imageTag is 'latest', else set to 'IfNotPresent'
|
||||
## ref: http://kubernetes.io/docs/user-guide/images/#pre-pulling-images
|
||||
##
|
||||
# imagePullPolicy:
|
||||
|
||||
## Specify password for root user
|
||||
## ref: https://github.com/bitnami/bitnami-docker-mariadb/blob/master/README.md#setting-the-root-password-on-first-run
|
||||
##
|
||||
# mariadbRootPassword:
|
||||
|
||||
## Create a database user
|
||||
## ref: https://github.com/bitnami/bitnami-docker-mariadb/blob/master/README.md#creating-a-database-user-on-first-run
|
||||
##
|
||||
# mariadbUser:
|
||||
# mariadbPassword:
|
||||
|
||||
## Create a database
|
||||
## ref: https://github.com/bitnami/bitnami-docker-mariadb/blob/master/README.md#creating-a-database-on-first-run
|
||||
##
|
||||
# mariadbDatabase:
|
||||
```
|
||||
|
||||
You can then override any of these settings in a YAML formatted file,
|
||||
and then pass that file during installation.
|
||||
|
||||
```console
|
||||
$ echo 'mariadbUser: user0` > config.yaml
|
||||
$ glide install -f config.yaml stable/mariadb
|
||||
```
|
||||
|
||||
The above will set the default MariaDB user to `user0`, but accept all
|
||||
the rest of the defaults for that chart.
|
||||
|
||||
## '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
|
||||
the configuration of your release, you can use the `helm upgrade`
|
||||
command.
|
||||
|
||||
An upgrade takes an existing release and upgrades it according to the
|
||||
information you provide. Because Kubernetes charts can be large and
|
||||
complex, Helm tries to perform the least invasive upgrade. It will only
|
||||
update things that have changed since the last release.
|
||||
|
||||
```console
|
||||
$ helm upgrade -f panda.yaml happy-panda stable/mariadb-0.3.0.tgz 1 ↵
|
||||
Fetched stable/mariadb-0.3.0.tgz to /Users/mattbutcher/Code/Go/src/k8s.io/helm/mariadb-0.3.0.tgz
|
||||
happy-panda has been upgraded. Happy Helming!
|
||||
Last Deployed: Wed Sep 28 12:47:54 2016
|
||||
Namespace: default
|
||||
Status: DEPLOYED
|
||||
...
|
||||
```
|
||||
|
||||
In the above case, the `happy-panda` release is upgraded with the same
|
||||
chart, but with a new YAML file:
|
||||
|
||||
```yaml
|
||||
mariadbUser: user1
|
||||
```
|
||||
|
||||
We can use `helm get values` to see whether that new setting took
|
||||
effect.
|
||||
|
||||
```console
|
||||
$ helm get values happy-panda
|
||||
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` were deployed to the cluster.
|
||||
|
||||
Now, if something does not go as planned during a release, it is easy to
|
||||
roll back to a previous release.
|
||||
|
||||
```console
|
||||
$ helm rollback happy-panda --version 1
|
||||
```
|
||||
|
||||
The above rolls back our happy-panda to its very first release version.
|
||||
A release version is an incremental revision. Every time an install,
|
||||
upgrade, or rollback happens, the revision number is incremented by 1.
|
||||
The first revision number is always 1.
|
||||
|
||||
## 'helm delete': Deleting a Release
|
||||
|
||||
When it is time to uninstall or delete a release from the cluster, use
|
||||
the `helm delete` command:
|
||||
|
||||
```
|
||||
$ helm delete happy-panda
|
||||
```
|
||||
|
||||
This will remove the release from the cluster. You can see all of your
|
||||
currently deployed releases with 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.0
|
||||
```
|
||||
|
||||
From the output above, we can see that the `happy-panda` release was
|
||||
deleted.
|
||||
|
||||
However, Helm always keeps records of what releases happened. Need to
|
||||
see the deleted releases? `helm list --deleted` shows those, and `helm
|
||||
list --all` shows all of the releases (deleted and currently deployed,
|
||||
as well as releases that failed):
|
||||
|
||||
```console
|
||||
⇒ helm list --all
|
||||
NAME VERSION UPDATED STATUS CHART
|
||||
happy-panda 2 Wed Sep 28 12:47:54 2016 DELETED mariadb-0.3.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 DELETED alpine-0.1.0
|
||||
```
|
||||
|
||||
Because Helm keeps records of deleted releases, a release name cannot be
|
||||
re-used. (If you _really_ need to re-use a release name, you can use the
|
||||
`--replace` flag, but it will simply re-use the existing release and
|
||||
replace its resources.)
|
||||
|
||||
Note that because releases are preserved in this way, you can rollback a
|
||||
deleted resource, and have it re-activate.
|
||||
|
||||
## 'helm repo': Working with Repositories
|
||||
|
||||
So far, we've been installing charts only from the `stable` repository.
|
||||
But you can configure `helm` to use other repositories. Helm provides
|
||||
several repository tools under the `helm repo` command.
|
||||
|
||||
You can see which repositories are configured using `helm repo list`:
|
||||
|
||||
```console
|
||||
$ helm repo list
|
||||
NAME URL
|
||||
stable http://storage.googleapis.com/kubernetes-charts
|
||||
local http://localhost:8879/charts
|
||||
mumoshu https://mumoshu.github.io/charts
|
||||
```
|
||||
|
||||
And new repositories can be added with `helm repo add`:
|
||||
|
||||
```console
|
||||
$ helm repo add dev https://example.com/dev-charts
|
||||
```
|
||||
|
||||
Because chart repositories change frequently, at any point you can make
|
||||
sure your Helm client is up to date by running `helm update`.
|
||||
|
||||
## Creating Your Own Charts
|
||||
|
||||
The [Chart Development Guide](chart.md) explains how to develop your own
|
||||
charts. But you can get started quickly by using the `helm create`
|
||||
command:
|
||||
|
||||
```console
|
||||
$ helm create deis-workflow
|
||||
Creating deis-workflow
|
||||
```
|
||||
|
||||
Now there is a chart in `./deis-workflow`. You can edit it and create
|
||||
your own templates.
|
||||
|
||||
As you edit your chart, you can validate that it is well-formatted by
|
||||
running `helm lint`.
|
||||
|
||||
When it's time to package the chart up for distribution, you can run the
|
||||
`helm package` command:
|
||||
|
||||
```console
|
||||
$ helm package deis-workflow
|
||||
deis-workflow-0.1.0.tgz
|
||||
```
|
||||
|
||||
And that chart can now easily be installed by `helm install`:
|
||||
|
||||
```console
|
||||
$ helm install ./deis-workflow-0.1.0.tgz
|
||||
...
|
||||
```
|
||||
|
||||
Charts that are archived can be loaded into chart repositories. See the
|
||||
documentation for your chart repository server to learn how to upload.
|
||||
|
||||
Note: The `stable` repository is managed on the [Kubernetes Charts
|
||||
GitHub repository](https://github.com/kubernetes/charts). That project
|
||||
accepts chart source code, 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 deleting. It has also
|
||||
covered 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.
|
Loading…
Reference in new issue