From 627c59d148cd690910d512d13a9f7ef89ddaed1e Mon Sep 17 00:00:00 2001 From: Matt Butcher Date: Fri, 14 Oct 2016 15:51:24 -0600 Subject: [PATCH] docs(*): refresh docs This refreshes docs, as discussed in #719, and adds a few new sections to the docs. Closes #719 --- README.md | 3 + docs/architecture.md | 23 +---- docs/charts.md | 175 ++++----------------------------- docs/charts_hooks.md | 150 ++++++++++++++++++++++++++++ docs/charts_tips_and_tricks.md | 71 +++++++++++++ docs/developers.md | 23 ++++- docs/history.md | 4 +- docs/install.md | 22 ++++- docs/quickstart.md | 78 ++++++++------- docs/using_helm.md | 46 +++++---- 10 files changed, 358 insertions(+), 237 deletions(-) create mode 100644 docs/charts_hooks.md create mode 100644 docs/charts_tips_and_tricks.md diff --git a/README.md b/README.md index 6d9acdd32..76cc7d5a2 100644 --- a/README.md +++ b/README.md @@ -50,8 +50,11 @@ including installing pre-releases. - [Installing Helm](docs/install.md) - [Using Helm](docs/using_helm.md) - [Developing Charts](docs/charts.md) + - [Chart Lifecycle Hooks](docs/chart_hooks.md) + - [Chart Tips and Tricks](docs/chart_tips_and_tricks.md) - [Chart Repository Guide](docs/chart_repository.md) - [Syncing your Chart Repository](docs/chart_repository_sync_example.md) + - [Signing Charts](docs/provenance.md) - [Architecture](docs/architecture.md) - [Developers](docs/developers.md) - [History](docs/history.md) diff --git a/docs/architecture.md b/docs/architecture.md index 1d5134f12..752a7e12c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -11,7 +11,7 @@ can do the following: - Package charts into chart archive (tgz) files - Interact with chart repositories where charts are stored - Install and uninstall charts into an existing Kubernetes cluster -- Manage the releases of charts that have been installed with Helm +- Manage the release cycle of charts that have been installed with Helm For Helm, there are three important concepts: @@ -22,9 +22,6 @@ For Helm, there are three important concepts: 3. A _release_ is a running instance of a _chart_, combined with a specific _config_. -Following the formula made famous by the [12 Factor App](http://12factor.net/), _chart + config -= release_. - ## Components Helm has two major components: @@ -64,20 +61,4 @@ communicate with Kubernetes. Currently, that library uses REST+JSON. The Tiller server stores information in ConfigMaps located inside of Kubernetes. It does not need its own database. -### Structure of the Code - -The individual programs are located in `cmd/`. Shared libraries are -stored in `pkg/`. The raw ProtoBuf files are stored in `_proto/hapi` -(where `hapi` stands for the Helm Application Programming Interface). -The Go files generated from the `proto` definitions are stored in -`pkg/proto`. - -Docker images are built by cross-compiling Linux binaries and then -building a Docker image from the files in `rootfs`. - -The `scripts/` directory contains a number of utility scripts. Most of these -are used by the CI/CD pipeline. - -Go dependencies are managed with -[Glide](https://github.com/Masterminds/glide) and stored in the -`vendor/` directory. +Configuration files are, when possible, written in YAML. diff --git a/docs/charts.md b/docs/charts.md index f94fdb22d..7eac4a130 100644 --- a/docs/charts.md +++ b/docs/charts.md @@ -32,7 +32,8 @@ wordpress/ templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes ``` -Helm will silently strip out any other files. +Helm reserves use of the `charts/` and `templates/` directories, and of +the listed file names. Other files will be left as they are. ## The Chart.yaml File @@ -204,16 +205,18 @@ team. ## Templates and Values -By default, Helm Chart templates are written in the Go template language, with the -addition of 50 or so [add-on template -functions](https://github.com/Masterminds/sprig). (In the future, Helm -may support other template languages, like Python Jinja.) +Helm Chart templates are written in the +[Go template language](https://golang.org/pkg/text/template/), with the +addition of 50 or so add-on template +functions [from the Sprig library](https://github.com/Masterminds/sprig) and a +few other [specialized functions](charts_tips_and_tricks.md). All template files are stored in a chart's `templates/` folder. When Helm renders the charts, it will pass every file in that directory through the template engine. Values for the templates are supplied two ways: + - Chart developers may supply a file called `values.yaml` inside of a chart. This file can contain default values. - Chart users may supply a YAML file that contains values. This can be @@ -221,6 +224,7 @@ Values for the templates are supplied two ways: When a user supplies custom values, these values will override the values in the chart's `values.yaml` file. + ### Template Files Template files follow the standard conventions for writing Go templates @@ -269,6 +273,9 @@ It can use the following four template values (usually defined in a All of these values are defined by the template author. Helm does not require or dictate parameters. +To see many working charts, check out the [Kubernetes Charts +project](https://github.com/kubernetes/charts) + ### Predefined Values Values that are supplied via a `values.yaml` file (or via the `--set` @@ -296,7 +303,8 @@ sensitive_. **NOTE:** Any unknown Chart.yaml fields will be dropped. They will not be accessible inside of the `Chart` object. Thus, Chart.yaml cannot be -used to pass arbitrarily structured data into the template. +used to pass arbitrarily structured data into the template. The values +file can be used for that, though. ### Values files @@ -342,6 +350,9 @@ Note that only the last field was overridden. `values.yaml`. But files specified on the command line can be named anything. +**NOTE:** If the `--set` flag is used on `helm install` or `helm upgrade`, those +values are simply converted to YAML on the client side. + Any of these values are then accessible inside of templates using the `.Values` object: @@ -479,157 +490,7 @@ standard references that will help you out. - [Go templates](https://godoc.org/text/template) - [Extra template functions](https://godoc.org/github.com/Masterminds/sprig) -- [The YAML format]() - -## Hooks - -Helm provides a _hook_ mechanism to allow chart developers to intervene -at certain points in a release's life cycle. For example, you can use -hooks to: - -- Load a ConfigMap or Secret during install before any other charts are - loaded. -- Execute a Job to backup up a database before installing a new chart, - and then execute a second job after the upgrade in order to restore - data. -- Run a Job before deleting a release to gracefully take a service out - of rotation before removing it. - -Hooks work like regular templates, but they have special annotations -that cause Helm to utilize them differently. In this section, we cover -the basic usage pattern for hooks. - -### The Available Hooks - -The following hooks are defined: - -- pre-install: Executes after templates are rendered, but before any - resources are created in Kubernetes. -- post-install: Executes after all resources are loaded into Kubernetes -- pre-delete: Executes on a deletion request before any resources are - deleted from Kubernetes. -- post-delete: Executes on a deletion request after all of the release's - resources have been deleted. -- pre-upgrade: Executes on an upgrade request after templates are - rendered, but before any resources are loaded into Kubernetes (e.g. - before a kuberntes apply operation). -- post-upgrade: Executes on an upgrade after all resources have been - upgraded. - -### Hooks and the Release Lifecycle - -Hooks allow you, the chart developer, an opportunity to perform -operations at strategic points in a release lifecycle. For example, -consider the lifecycle for a `helm install`. By default, the lifecycle -looks like this: - -1. User runs `helm install foo` -2. Chart is loaded into Tiller -3. After some verification, Tiller renders the `foo` templates -4. Tiller loads the resulting resources into Kubernetes -5. Tiller returns the release name (and other data) to the client -6. The client exits - -Helm defines two hooks for the `install` lifecycle: `pre-install` and -`post-install`. If the developer of the `foo` chart implements both -hooks, the lifecycle is altered like this: - -1. User runs `helm install foo` -2. Chart is loaded into Tiller -3. After some verification, Tiller renders the `foo` templates -4. Tiller executes the `pre-install` hook (loading hook resources into - Kubernetes) -5. Tiller waits until the hook is "Ready" -6. Tiller loads the resulting resources into Kubernetes -7. Tiller executes the `post-install` hook (loading hook resources) -8. Tiller waits until the hook is "Ready" -9. Tiller returns the release name (and other data) to the client -10. The client exits - -What does it mean to wait until a hook is ready? This depends on the -resource declared in the hook. If the resources is a `Job` kind, Tiller -will wait until the job successfully runs to completion. And if the job -fails, the release will fail. This is a _blocking operation_, so the -Helm client will pause while the Job is run. - -For all other kinds, as soon as Kubernetes marks the resource as loaded -(added or updated), the resource is considered "Ready". When many -resources are declared in a hook, the resources are executed serially, -but the order of their execution is not guaranteed. - -#### Hook resources are unmanaged - -The resources that a hook creates are not tracked or managed as part of the -release. Once Tiller verifies that the hook has reached its ready state, it -will leave the hook resource alone. - -Practically speaking, this means that if you create resources in a hook, you -cannot rely upon `helm delete` to remove the resources. To destroy such -resources, you need to write code to perform this operation in a `pre-delete` -or `post-delete` hook. - -### Writing a Hook - -Hooks are just Kubernetes manfiest files with special annotations in the -`metadata` section. Because they are template files, you can use all of -the normal template features, including reading `.Values`, `.Release`, -and `.Template`. - -For example, this template, stored in `templates/post-install-job.yaml`, -declares a job to be run on `post-install`: - -```yaml -apiVersion: batch/v1 -kind: Job -metadata: - name: "{{.Release.Name}}" - labels: - heritage: {{.Release.Service | quote }} - release: {{.Release.Name | quote }} - chart: "{{.Chart.Name}}-{{.Chart.Version}}" - annotations: - # This is what defines this resource as a hook. Without this line, the - # job is considered part of the release. - "helm.sh/hook": post-install -spec: - template: - metadata: - name: "{{.Release.Name}}" - labels: - heritage: {{.Release.Service | quote }} - release: {{.Release.Name | quote }} - chart: "{{.Chart.Name}}-{{.Chart.Version}}" - spec: - restartPolicy: Never - containers: - - name: post-install-job - image: "alpine:3.3" - command: ["/bin/sleep","{{default "10" .Values.sleepyTime}}"] - -``` - -What makes this template a hook is the annotation: - -``` - annotations: - "helm.sh/hook": post-install -``` - -One resource can implement multiple hooks: - -``` - annotations: - "helm.sh/hook": post-install,post-upgrade -``` - -Similarly, there is no limit to the number of different resources that -may implement a given hook. For example, one could declare both a secret -as a config map as a pre-install hook. It is important to keep in mind, -though, that there are no ordering guarantees about hooks. - -When subcharts declare hooks, those are also evaluated. There is no way -for a top-level chart to disable the hooks declared by subcharts. And -again, there is no guaranteed ordering. +- [The YAML format](http://yaml.org/spec/) ## Using Helm to Manage Charts diff --git a/docs/charts_hooks.md b/docs/charts_hooks.md new file mode 100644 index 000000000..563dc4e78 --- /dev/null +++ b/docs/charts_hooks.md @@ -0,0 +1,150 @@ +# Hooks + +Helm provides a _hook_ mechanism to allow chart developers to intervene +at certain points in a release's life cycle. For example, you can use +hooks to: + +- Load a ConfigMap or Secret during install before any other charts are + loaded. +- Execute a Job to backup up a database before installing a new chart, + and then execute a second job after the upgrade in order to restore + data. +- Run a Job before deleting a release to gracefully take a service out + of rotation before removing it. + +Hooks work like regular templates, but they have special annotations +that cause Helm to utilize them differently. In this section, we cover +the basic usage pattern for hooks. + +## The Available Hooks + +The following hooks are defined: + +- pre-install: Executes after templates are rendered, but before any + resources are created in Kubernetes. +- post-install: Executes after all resources are loaded into Kubernetes +- pre-delete: Executes on a deletion request before any resources are + deleted from Kubernetes. +- post-delete: Executes on a deletion request after all of the release's + resources have been deleted. +- pre-upgrade: Executes on an upgrade request after templates are + rendered, but before any resources are loaded into Kubernetes (e.g. + before a kuberntes apply operation). +- post-upgrade: Executes on an upgrade after all resources have been + upgraded. + +## Hooks and the Release Lifecycle + +Hooks allow you, the chart developer, an opportunity to perform +operations at strategic points in a release lifecycle. For example, +consider the lifecycle for a `helm install`. By default, the lifecycle +looks like this: + +1. User runs `helm install foo` +2. Chart is loaded into Tiller +3. After some verification, Tiller renders the `foo` templates +4. Tiller loads the resulting resources into Kubernetes +5. Tiller returns the release name (and other data) to the client +6. The client exits + +Helm defines two hooks for the `install` lifecycle: `pre-install` and +`post-install`. If the developer of the `foo` chart implements both +hooks, the lifecycle is altered like this: + +1. User runs `helm install foo` +2. Chart is loaded into Tiller +3. After some verification, Tiller renders the `foo` templates +4. Tiller executes the `pre-install` hook (loading hook resources into + Kubernetes) +5. Tiller waits until the hook is "Ready" +6. Tiller loads the resulting resources into Kubernetes +7. Tiller executes the `post-install` hook (loading hook resources) +8. Tiller waits until the hook is "Ready" +9. Tiller returns the release name (and other data) to the client +10. The client exits + +What does it mean to wait until a hook is ready? This depends on the +resource declared in the hook. If the resources is a `Job` kind, Tiller +will wait until the job successfully runs to completion. And if the job +fails, the release will fail. This is a _blocking operation_, so the +Helm client will pause while the Job is run. + +For all other kinds, as soon as Kubernetes marks the resource as loaded +(added or updated), the resource is considered "Ready". When many +resources are declared in a hook, the resources are executed serially, +but the order of their execution is not guaranteed. + +### Hook resources are unmanaged + +The resources that a hook creates are not tracked or managed as part of the +release. Once Tiller verifies that the hook has reached its ready state, it +will leave the hook resource alone. + +Practically speaking, this means that if you create resources in a hook, you +cannot rely upon `helm delete` to remove the resources. To destroy such +resources, you need to write code to perform this operation in a `pre-delete` +or `post-delete` hook. + +## Writing a Hook + +Hooks are just Kubernetes manfiest files with special annotations in the +`metadata` section. Because they are template files, you can use all of +the normal template features, including reading `.Values`, `.Release`, +and `.Template`. + +For example, this template, stored in `templates/post-install-job.yaml`, +declares a job to be run on `post-install`: + +```yaml +apiVersion: batch/v1 +kind: Job +metadata: + name: "{{.Release.Name}}" + labels: + heritage: {{.Release.Service | quote }} + release: {{.Release.Name | quote }} + chart: "{{.Chart.Name}}-{{.Chart.Version}}" + annotations: + # This is what defines this resource as a hook. Without this line, the + # job is considered part of the release. + "helm.sh/hook": post-install +spec: + template: + metadata: + name: "{{.Release.Name}}" + labels: + heritage: {{.Release.Service | quote }} + release: {{.Release.Name | quote }} + chart: "{{.Chart.Name}}-{{.Chart.Version}}" + spec: + restartPolicy: Never + containers: + - name: post-install-job + image: "alpine:3.3" + command: ["/bin/sleep","{{default "10" .Values.sleepyTime}}"] + +``` + +What makes this template a hook is the annotation: + +``` + annotations: + "helm.sh/hook": post-install +``` + +One resource can implement multiple hooks: + +``` + annotations: + "helm.sh/hook": post-install,post-upgrade +``` + +Similarly, there is no limit to the number of different resources that +may implement a given hook. For example, one could declare both a secret +as a config map as a pre-install hook. It is important to keep in mind, +though, that there are no ordering guarantees about hooks. + +When subcharts declare hooks, those are also evaluated. There is no way +for a top-level chart to disable the hooks declared by subcharts. And +again, there is no guaranteed ordering. + diff --git a/docs/charts_tips_and_tricks.md b/docs/charts_tips_and_tricks.md new file mode 100644 index 000000000..5919d77c2 --- /dev/null +++ b/docs/charts_tips_and_tricks.md @@ -0,0 +1,71 @@ +# Chart Development Tips and Tricks + +This guide covers some of the tips and tricks Helm chart developers have +learned while building production-quality charts. + +## Quote Strings, Don't Quote Integers + +When you are working with string data, you are always safer quoting the +strings than leaving them as bare words: + +``` +name: {{.Values.MyName | quote }} +``` + +But when working with integers _do not quote the values._ That can, in +many cases, cause parsing errors inside of Kubernetes. + +``` +port: {{ .Values.Port }} +``` + +## Using the 'include' Function + +Go provides a way of including one template in another using a built-in +`template` directive. However, the built-in function cannot be used in +Go template pipelines. + +To make it possible to include a template, and then perform an operation +on that template's output, Helm has a special `include` function: + +``` +{{ include "toYaml" $value | indent 2 }} +``` + +The above includes a template called `toYaml`, passes it `$value`, and +then passes the output of that template to the `indent` function. + +Because YAML ascribes significance to indentation levels and whitespace, +this is one great way to include snippets of code, but handle +indentation in a relevant context. + +## Using "Partials" and Template Includes + +Sometimes you want to create some reusable parts in your chart, whether +they're blocks or template partials. And often, it's cleaner to keep +these in their own files. + +In the `templates/` directory, any file that begins with an +underscore(`_`) is not expected to ouput a Kubernetes manifest file. So +by convention, helper templates and partials are placed in a +`_helpers.tpl` file. + +## YAML is a Superset of JSON + +According to the YAML specification, YAML is a superset of JSON. That +means that any valid JSON structure ought to be valid in YAML. + +This has an advantage: Sometimes template developers may find it easier +to express a datastructure with a JSON-like syntax rather than deal with +YAML's whitespace sensitivity. + +As a best practice, templates should follow a YAML-like syntax _unless_ +the JSON syntax substantially reduces the risk of a formatting issue. + +## Be Careful with Generating Random Values + +There are functions in Helm that allow you to generate random data, +cryptographic keys, and so on. These are fine to use. But be aware that +during upgrades, templates are re-executed. When a template run +generates data that differs from the last run, that will trigger an +update of that resource. diff --git a/docs/developers.md b/docs/developers.md index a88abcb4e..f5f9cf8d2 100644 --- a/docs/developers.md +++ b/docs/developers.md @@ -104,6 +104,25 @@ Make sure you have read and understood the main CONTRIBUTING guide: https://github.com/kubernetes/helm/blob/master/CONTRIBUTING.md +### Structure of the Code + +The code for the Helm project is organized as follows: + +- The individual programs are located in `cmd/`. Code inside of `cmd/` + is not designed for library re-use. +- Shared libraries are stored in `pkg/`. +- The raw ProtoBuf files are stored in `_proto/hapi` (where `hapi` stands for + the Helm Application Programming Interface). +- The Go files generated from the `proto` definitions are stored in `pkg/proto`. +- The `scripts/` directory contains a number of utility scripts. Most of these + are used by the CI/CD pipeline. +- The `rootfs/` folder is used for Docker-specific files. +- The `docs/` folder is used for documentation and examples. + +Go dependencies are managed with +[Glide](https://github.com/Masterminds/glide) and stored in the +`vendor/` directory. + ### Git Conventions We use Git for our version control system. The `master` branch is the @@ -145,7 +164,7 @@ Common scopes: - tiller: The Tiller server - proto: Protobuf definitions - pkg/lint: The lint package. Follow a similar convention for any - package, + package - `*`: two or more scopes Read more: @@ -159,7 +178,7 @@ We follow the Go coding style standards very closely. Typically, running `go fmt` will make your code beautiful for you. We also typically follow the conventions recommended by `go lint` and -`govet`. Run `make test-style` to test the style conformance. +`gometalinter`. Run `make test-style` to test the style conformance. Read more: diff --git a/docs/history.md b/docs/history.md index 827e684fb..71e63c6b2 100644 --- a/docs/history.md +++ b/docs/history.md @@ -3,7 +3,7 @@ Kubernetes Helm is the merged result of [Helm Classic](https://github.com/helm/helm) and the Kubernetes port of GCS Deployment Manager. The project was jointly started by Google and Deis, though it -is now part of the CNCF. +is now part of the CNCF. Many companies now contribute regularly to Helm. Differences from Helm Classic: @@ -18,7 +18,7 @@ Differences from Helm Classic: or `template` commands. - Helm makes it easy to configure your releases -- and share the configuration with the rest of your team. -- Helm chart repositories now use plain HTTP instead of Git/GitHub. +- Helm chart repositories now use plain HTTP(S) instead of Git/GitHub. There is no longer any GitHub dependency. - A chart server is a simple HTTP server - Charts are referenced by version diff --git a/docs/install.md b/docs/install.md index fe54e2487..f781889dc 100644 --- a/docs/install.md +++ b/docs/install.md @@ -9,7 +9,7 @@ proceeds to show two ways to install the server. The Helm client can be installed either from source, or from pre-built binary releases. -### From the GitHub Releases +### From the Binary Releases Every [release](https://github.com/kubernetes/helm/releases) of Helm provides binary releases for a variety of OSes. These binary versions @@ -53,7 +53,8 @@ Here are links to the common builds: 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 with [glide](https://github.com/Masterminds/glide) and Mercurial installed. +You must have a working Go environment with +[glide](https://github.com/Masterminds/glide) and Mercurial installed. ```console $ cd $GOPATH @@ -88,6 +89,12 @@ view`). Once it connects, it will install `tiller` into the After `helm init`, you should be able to run `kubectl get po --namespace kube-system` and see Tiller running. +You can explicitly tell `helm init` to... + +- Install the canary build with the `--canary-image` flag +- Install a particular image (version) with `--tiller-image` +- Install to a particular cluster with `--kube-context` + 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 @@ -99,10 +106,10 @@ Canary images are built from the `master` branch. They may not be stable, but they offer you the chance to test out the latest features. The easiest way to install a canary image is to use `helm init` with the -`--tiller-image` flag: +`--canary-image` flag: ```console -$ helm init -i "gcr.io/kubernetes-helm/tiller:canary" +$ helm init --canary-image ``` This will use the most recently built container image. You can always @@ -142,6 +149,13 @@ Server: &version.Version{SemVer:"v2.0.0-alpha.4", GitCommit:"a5...", GitTreeStat Importantly, even when running locally, Tiller will store release configuration in ConfigMaps inside of Kubernetes. +## Deleting or Reinstalling Tiller + +Because Tiller stores its data in Kubernetes ConfigMaps, you can safely +delete and re-install Tiller without worrying about losing any data. The +recommended way of deleting Tiller is with `kubectl delete deployment +tiller-deployment -n kube-system` + ## Conclusion In most cases, installation is as simple as getting a pre-built `helm` binary diff --git a/docs/quickstart.md b/docs/quickstart.md index 3266f9151..41bf1ea89 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -4,22 +4,29 @@ This guide covers how you can quickly get started using Helm. ## Prerequisites -- You must have Kubernetes installed, and have a local configured copy - of `kubectl`. +- You must have Kubernetes installed. We recommend version 1.4.1 or + later. +- You should also have a local configured copy of `kubectl`. Helm will figure out where to install Tiller by reading your Kubernetes configuration file (usually `$HOME/.kube/config`). This is the same file -that `kubectl` uses, so to find out which cluster Tiller would install -to, you can run `kubectl cluster-info`. +that `kubectl` uses. + +To find out which cluster Tiller would install to, you can run +`kubectl config current-context` or `kubectl cluster-info`. + +```console +$ kubectl config current-context +my-cluster +``` ## Install Helm -Download a binary release of the Helm client from -[the official project page](https://github.com/kubernetes/helm/releases). +Download a binary release of the Helm client. You can use tools like +`homebrew`, or look at [the official releases page](https://github.com/kubernetes/helm/releases). -Alternately, you can clone the GitHub project and build your own -client from source. The quickest route to installing from source is to -run `make bootstrap build`, and then use `bin/helm`. +For more details, or for other options, see [the installation +guide](install.md). ## Initialize Helm and Install Tiller @@ -30,47 +37,47 @@ install Tiller into your Kubernetes cluster in one step: $ helm init ``` -## Install an Example Chart +This will install Tiller into the Kubernetes cluster you saw with +`kubectl config current-context`. + +**TIP:** Want to install into a different cluster? Use the +`--kube-context` flag. -To install a chart, you can run the `helm install` command. -Let's use an example chart from this repository. -Make sure you are in the root directory of this repo. +## Install an Example Chart +To install a chart, you can run the `helm install` command. Helm has +several ways to find and install a chart, but the easiest is to use one +of the official `stable` charts. ```console +$ helm repo update # Make sure we get the latest list of charts $ helm install stable/mysql Released smiling-penguin ``` In the example above, the `stable/mysql` chart was released, and the name of -our new release is `smiling-penguin`. You get a simple idea of this -MySQL chart by running `helm inspect stable/mysql`. +our new release is `smiling-penguin`. You get a simple idea of the +features of this MySQL chart by running `helm inspect stable/mysql`. -## Change a Default Chart Value +Whenever you install a chart, a new release is created. So one chart can +be installed multiple times into the same cluster. And each can be +independently managed and upgrade. -A nice feature of helm is the ability to change certain values of the package for the install. -Let's install the `nginx` example from this repository but change the `replicaCount` to 7. +The `helm install` command is a very powerful command with many +capabilities. To learn more about it, check out the [Using Helm +Guide](using_helm.md) -```console -$ helm install --set replicaCount=7 ./docs/examples/nginx -happy-panda -``` - -You can view the chart for this example in -[docs/examples/nginx/Chart.yaml](examples/nginx/Chart.yaml) and the default values in -[docs/examples/nginx/values.yaml](examples/nginx/values.yaml). +## Learn About Releases -## Learn About The Release - -To find out about our release, run `helm status`: +It's easy to see what has been released using Helm: ```console -$ helm status smiling-penguin -Status: DEPLOYED +$ helm ls +NAME VERSION UPDATED STATUS CHART +smiling-penguin 1 Wed Sep 28 12:59:46 2016 DEPLOYED mysql-0.1.0 ``` -The `status` command will display information about a release in your -cluster. +The `helm list` function will show you a list of all deployed releases. ## Uninstall a Release @@ -87,8 +94,13 @@ still be able to request information about that release: ```console $ helm status smiling-penguin Status: DELETED +... ``` +Because Helm tracks your releases even after you've deleted them, you +can 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 type diff --git a/docs/using_helm.md b/docs/using_helm.md index 41ae8b444..d688e0700 100644 --- a/docs/using_helm.md +++ b/docs/using_helm.md @@ -13,8 +13,8 @@ covers the particulars of Helm commands, and explains how to use Helm. 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. +cluster. Think of it like the Kubernetes equivalent of a Homebrew formula, +an Apt dpkg, or a Yum RPM file. A *Repository* is the place where charts can be collected and shared. It's like Perl's [CPAN archive](http://www.cpan.org) or the @@ -45,9 +45,11 @@ You can see which charts are available by running `helm search`: ``` $ helm search -stable/drupal -stable/jenkins -stable/mariadb +NAME VERSION DESCRIPTION +stable/drupal 0.3.2 One of the most versatile open source content m... +stable/jenkins 0.1.0 A Jenkins Helm chart for Kubernetes. +stable/mariadb 0.5.1 Chart for MariaDB +stable/mysql 0.1.0 Chart for MySQL ... ``` @@ -56,17 +58,22 @@ can narrow down your results by searching with a filter: ``` $ helm search mysql -stable/mysql -stable/mariadb +NAME VERSION DESCRIPTION +stable/mysql 0.1.0 Chart for MySQL +stable/mariadb 0.5.1 Chart for 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: +Now you will only see the results that match your filter. MySQL is +listed, of course, but so is MariaDB. Why? Because its full description +relates it to MySQL: + +Why is +`mariadb` in the list? Because its package description relates it to +MySQL. 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 +Fetched stable/mariadb to mariadb-0.5.1.tgz description: Chart for MariaDB engine: gotpl home: https://mariadb.org @@ -75,13 +82,7 @@ keywords: - 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 @@ -223,6 +224,15 @@ $ helm 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. +### More Installation Methods + +The `helm install` command can install from several sources: + +- A chart repository (as we've seen above) +- A local chart archive (`helm install foo-0.1.1.tgz`) +- An unpacked chart directory (`helm install path/to/foo`) +- A full URL (`helm install https://example.com/charts/foo-1.2.3.tgz`) + ## '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