root
/
helm
mirror of https://github.com/helm/helm.git
1
0
Fork 0
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs(*): refresh docs 

This refreshes docs, as discussed in #719, and adds a few new sections
to the docs.

Closes #719
This commit is contained in:
Matt Butcher 2016-10-14 15:51:24 -06:00
parent bb2511a41b
commit 627c59d148
10 changed files with 360 additions and 239 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

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

23
docs/architecture.md
View File

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

175
docs/charts.md
View File

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

150
docs/charts_hooks.md Normal file
View File

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

71
docs/charts_tips_and_tricks.md Normal file
View File

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

23
docs/developers.md
View File

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

4
docs/history.md
View File

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

22
docs/install.md
View File

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

82
docs/quickstart.md
View File

@ -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
```
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.
## Install an Example Chart
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.
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)
## Learn About Releases
It's easy to see what has been released using Helm:
```console
$ helm install --set replicaCount=7 ./docs/examples/nginx
happy-panda
$ helm ls
NAME VERSION UPDATED STATUS CHART
smiling-penguin 1 Wed Sep 28 12:59:46 2016 DEPLOYED mysql-0.1.0
```
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 The Release
To find out about our release, run `helm status`:
```console
$ helm status smiling-penguin
Status: DEPLOYED
```
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

46
docs/using_helm.md
View File

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