diff --git a/README.md b/README.md index a742816d2..15454f9a2 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 000000000..1a4578a9c --- /dev/null +++ b/docs/install.md @@ -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. diff --git a/docs/using_helm.md b/docs/using_helm.md new file mode 100644 index 000000000..369d39ee3 --- /dev/null +++ b/docs/using_helm.md @@ -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 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 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.