Merge pull request #1247 from technosophos/docs/install

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

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)
 - [Glossary](docs/glossary.md)

docs/install.md

+# 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.

docs/using_helm.md

+# 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.