msb-public
/
helm
mirror of https://github.com/helm/helm
1
0
Code Issues Projects Releases Wiki Activity

docs(install, using): add installation and usage docs

Browse Source
pull/1247/head
Matt Butcher 8 years ago
parent 3437e5d6e5
commit 7d8b5bbb49
3 changed files with 518 additions and 2 deletions
Show Stats Download Patch File Download Diff File

6
README.md
Unescape View File

@ -35,10 +35,12 @@ Download a [release tarball of helm for your platform](https://github.com/kubern
## Docs
- [Quick Start](docs/quickstart.md)
- [Architecture](docs/architecture.md)
- [Charts](docs/charts.md)
- [Installing Helm](docs/install.md)
- [Using Helm](docs/using_helm.md)
- [Developing Charts](docs/charts.md)
- [Chart Repository Guide](docs/chart_repository.md)
- [Syncing your Chart Repository](docs/chart_repository_sync_example.md)
- [Architecture](docs/architecture.md)
- [Developers](docs/developers.md)
- [History](docs/history.md)

122
docs/install.md
Unescape View File

@ -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.

392
docs/using_helm.md
Unescape View File

@ -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.
Write Preview
Loading…
Cancel
Save