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

Merge pull request #715 from technosophos/docs/updated-charts

Browse Source 
docs(chart): updated chart documentation
pull/720/head v2.0.0-alpha.1
Matt Butcher 8 years ago
parent 137867b434 26e003b931
commit 57c9861116
3 changed files with 174 additions and 30 deletions
Show Stats Download Patch File Download Diff File

3
_proto/hapi/chart/metadata.proto
Unescape View File

@ -37,4 +37,7 @@ message Metadata {
// A list of name and URL/email address combinations for the maintainer(s)
repeated Maintainer maintainers = 7;
// The name of the template engine to use. Defaults to 'gotpl'.
string engine = 8;
}

168
docs/charts.md
Unescape View File

@ -1,7 +1,16 @@
# Charts
Helm uses a packaging format called _charts_. A chart is a collection of files
that collectively describe a set of Kubernetes resources.
that describe a related set of Kubernetes resources. A single chart
might be used to deploy something simple, like a memcached pod, or
something complex, like a full web app stack with HTTP servers,
databases, caches, and so on.
Charts are created as files laid out in a particular directory tree,
then they can be packaged into versioned archives to be deployed.
This document explains the chart format, and provides basic guidance for
building charts with Helm.
## The Chart File Structure
@ -14,17 +23,19 @@ Inside of this directory, Helm will expect a structure that matches this:
```
wordpress/
Chart.yaml # A YAML file containing information about the chart
LICENSE # A plain text file containing the license for the chart
README.md # A human-readable README file
LICENSE # OPTIONAL: A plain text file containing the license for the chart
README.md # OPTIONAL: A human-readable README file
values.toml # The default configuration values for this chart
charts/ # A directory containing any charts upon which this chart depends.
templates/ # A directory of templates that, when combined with values,
# will generate valid Kubernetes manifest files.
```
Helm will silently strip out any other files.
## The Chart.yaml File
The Chart.yaml file is required for a chart. It contains the following fields:
The `Chart.yaml` file is required for a chart. It contains the following fields:
```yaml
name: The name of the chart (required)
@ -38,12 +49,15 @@ sources:
maintainers: # (optional)
- name: The maintainer's name (required for each maintainer)
email: The maintainer's email (optional for each maintainer)
engine: gotpl # The name of the template engine (optional, defaults to gotpl)
```
If you are familiar with the Chart.yaml file format for Helm Classic, you will
If you are familiar with the `Chart.yaml` file format for Helm Classic, you will
notice that fields specifying dependencies have been removed. That is because
the new Chart format expresses dependencies using the `charts/` directory.
Other fields will be silently ignored.
### Charts and Versioning
Every chart must have a version number. A version must follow the
@ -51,12 +65,38 @@ Every chart must have a version number. A version must follow the
Helm uses version numbers as release markers. Packages in repositories
are identified by name plus version.
For example, an `nginx` chart whose version field is set to `version:
1.2.3` will be named:
```
nginix-1.2.3.tgz
```
More complex SemVer 2 names are also supported, such as
`version: 1.2.3-alpha.1+ef365`. But non-SemVer names are explicitly
disallowed by the system.
**NOTE:** Whereas Helm Classic and Deployment Manager were both
very GitHub oriented when it came to charts, Kubernetes Helm does not
rely upon or require GitHub or even Git. Consequently, it does not use
Git SHAs for versioning at all.
The `version` field inside of the `Chart.yaml` is used by many of the
Helm tools, including the CLI and the Tiller server. When generating a
package, the `helm package` command will use the version that it finds
in the `Chart.yaml` as a token in the package name. The system assumes
that the version number in the chart package name matches the version number in
the `Chart.yaml`. Failure to meet this assumption will cause an error.
## Chart Dependencies
In Helm, one chart may depend on any number of other charts. These
dependencies are expressed explicitly by copying the dependency charts
into the `charts/` directory.
**Note:** The `dependencies:` section of the `Glide.yaml` from Helm
Classic has been completely removed.
For example, if the Wordpress chart depends on the Apache chart, the
Apache chart (of the correct version) is supplied in the Wordpress
chart's `charts/` directory:
@ -83,9 +123,10 @@ directory.
## Templates and Values
In Helm Charts, templates are written in the Go template language, with the
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).
functions](https://github.com/Masterminds/sprig). (In the future, Helm
may support other template languages, like Python Jinja.)
All template files are stored in a chart's `templates/` folder. When
Helm renders the charts, it will pass every file in that directory
@ -99,7 +140,6 @@ 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.toml` file.
### Template Files
Template files follow the standard conventions for writing Go templates.
@ -146,6 +186,26 @@ It can use the following four template values:
All of these values are defined by the template author. Helm does not
require or dictate parameters.
### Predefined Values
The following values are pre-defined, are available to every template, and
cannot be overridden. As with all values, the names are _case
sensitive_.
- `Release.Name`: The name of the release (not the chart)
- `Release.Time`: The time the chart release was last updated. This will
match the `Last Released` time on a Release object.
- `Release.Namespace`: The namespace the chart was released to.
- `Release.Service`: The service that conducted the release. Usually
this is `Tiller`.
- `Chart`: The contents of the `Chart.yaml`. Thus, the chart version is
obtainable as `Chart.Version` and the maintainers are in
`Chart.Maintainers`.
**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.
### Values files
Considering the template in the previous section, a `values.toml` file
@ -158,23 +218,76 @@ pullPolicy = "alwaysPull"
storage = "s3"
```
When a chart includes dependency charts, values can be supplied to those
charts using TOML tables:
A values file is formatted in TOML. A chart may include a default
`values.toml` file. The Helm install command allows a user to override
values by supplying additional TOML values:
```console
$ helm install --values=myvals.toml wordpress
```
When values are passed in this way, they will be merged into the default
values file. For example, consider a `myvals.toml` file that looks like
this:
```toml
storage = "gcs"
```
When this is merged with the `values.toml` in the chart, the resulting
generated content will be:
```toml
imageRegistry = "quay.io/deis"
dockerTag = "latest"
pullPolicy = "alwaysPull"
storage = "s3"
storage = "gcs"
```
Note that only the last field was overridden.
**NOTE:** The default values file included inside of a chart _must_ be named
`values.toml`. But files specified on the command line can be named
anything.
### Scope, Dependencies, and Values
Values files can declare values for the top-level chart, as well as for
any of the charts that are included in that chart's `charts/` directory.
Or, to phrase it differently, a values file can supply values to the
chart as well as to any of its dependencies. For example, the
demonstration Wordpress chart above has both `mysql` and `apache` as
dependencies. The values file could supply values to all of these
components:
```toml
title = "My Wordpress Site" # Sent to the Wordpress template
[router]
hostname = "example.com"
[mysql]
max_connections = 100 # Sent to MySQL
password = "secret"
[apache]
port = 8080 # Passed to Apache
```
In the above example, the value of `hostname` will be passed to a chart
named `router` (if it exists) in the `charts/` directory.
Charts at a higher level have access to all of the variables defined
beneath. So the wordpress chart can access `mysql.password`. But lower
level charts cannot access things in parent charts, so MySQL will not be
able to access the `title` property. Nor, for that matter, can it access
`apache.port`.
Values are namespaced, but namespaces are pruned. So for the Wordpress
chart, it can access the MySQL password field as `mysql.password`. But
for the MySQL chart, the scope of the values has been reduced and the
namespace prefix removed, so it will see the password field simply as
`password`.
### References
When it comes to writing templates and values files, there are several
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 TOML format](https://github.com/toml-lang/toml)
@ -205,3 +318,28 @@ formatting or information:
$ helm lint mychart
No issues found
```
## Chart Repositories
A _chart repository_ is an HTTP server that houses one or more packaged
charts. While `helm` can be used to manage local chart directories, when
it comes to sharing charts, the preferred mechanism is a chart
repository.
Any HTTP server that can serve YAML files and tar files and can answer
GET requests can be used as a repository server.
Helm comes with built-in package server for developer testing (`helm
serve`). The Helm team has tested other servers, including Google Cloud
Storage with website mode enabled, and S3 with website mode enabled.
A repository is characterized primarily by the presence of a special
file called `index.yaml` that has a list of all of the packages supplied
by the repository, together with metadata that allows retrieving and
verifying those packages.
On the client side, repositories are managed with the `helm repo`
commands. However, Helm does not provide tools for uploading charts to
remote repository servers. This is because doing so would add
substantial requirements to an implementing server, and thus raise the
barrier for setting up a repository.

33
pkg/proto/hapi/chart/metadata.pb.go
Unescape View File

@ -44,6 +44,8 @@ type Metadata struct {
Keywords []string `protobuf:"bytes,6,rep,name=keywords" json:"keywords,omitempty"`
// A list of name and URL/email address combinations for the maintainer(s)
Maintainers []*Maintainer `protobuf:"bytes,7,rep,name=maintainers" json:"maintainers,omitempty"`
// The name of the template engine to use. Defaults to 'gotpl'.
Engine string `protobuf:"bytes,8,opt,name=engine" json:"engine,omitempty"`
}
func (m *Metadata) Reset() { *m = Metadata{} }
@ -64,19 +66,20 @@ func init() {
}
var fileDescriptor2 = []byte{
// 224 bytes of a gzipped FileDescriptorProto
0x1f, 0x8b, 0x08, 0x00, 0x00, 0x09, 0x6e, 0x88, 0x02, 0xff, 0x6c, 0x90, 0x3f, 0x4f, 0xc4, 0x30,
0x0c, 0xc5, 0x55, 0xee, 0x7a, 0x3d, 0xdc, 0xcd, 0x42, 0x28, 0x30, 0x55, 0x37, 0x31, 0xe5, 0x24,
0x90, 0x10, 0x33, 0xfb, 0x2d, 0x37, 0xb2, 0x99, 0xd6, 0x52, 0x23, 0x48, 0x53, 0x25, 0x01, 0xc4,
0x97, 0xe5, 0xb3, 0x90, 0xba, 0xf4, 0xcf, 0xc0, 0x60, 0xc9, 0xef, 0xfd, 0xfc, 0x2c, 0xd9, 0x70,
0xd3, 0x52, 0x6f, 0x8e, 0x75, 0x4b, 0x3e, 0x1e, 0x2d, 0x47, 0x6a, 0x28, 0x92, 0xee, 0xbd, 0x8b,
0x0e, 0x61, 0x40, 0x5a, 0xd0, 0xe1, 0x11, 0xe0, 0x44, 0xa6, 0x8b, 0xa9, 0xd8, 0x23, 0xc2, 0xb6,
0x23, 0xcb, 0x2a, 0xab, 0xb2, 0xbb, 0xcb, 0xb3, 0xf4, 0x78, 0x05, 0x39, 0x5b, 0x32, 0xef, 0xea,
0x42, 0xcc, 0x51, 0x1c, 0x7e, 0x32, 0xd8, 0x9f, 0xfe, 0xd6, 0xfe, 0x1b, 0x4b, 0x5e, 0xeb, 0x92,
0x37, 0xa6, 0xa4, 0x47, 0x05, 0x45, 0x70, 0x1f, 0xbe, 0xe6, 0xa0, 0x36, 0xd5, 0x26, 0xd9, 0x93,
0x1c, 0xc8, 0x27, 0xfb, 0x60, 0x5c, 0xa7, 0xb6, 0x12, 0x98, 0x24, 0x56, 0x50, 0x36, 0x1c, 0x6a,
0x6f, 0xfa, 0x38, 0xd0, 0x5c, 0xe8, 0xda, 0xc2, 0x5b, 0xd8, 0xbf, 0xf1, 0xf7, 0x97, 0xf3, 0x4d,
0x50, 0x3b, 0x59, 0x3b, 0x6b, 0x7c, 0x82, 0xd2, 0xce, 0xe7, 0x05, 0x55, 0x24, 0x5c, 0xde, 0x5f,
0xeb, 0xe5, 0x01, 0x7a, 0xb9, 0xfe, 0xbc, 0x1e, 0x7d, 0x2e, 0x5e, 0x72, 0x19, 0x78, 0xdd, 0xc9,
0xd3, 0x1e, 0x7e, 0x03, 0x00, 0x00, 0xff, 0xff, 0xb9, 0xaf, 0x44, 0xa7, 0x51, 0x01, 0x00, 0x00,
// 234 bytes of a gzipped FileDescriptorProto
0x1f, 0x8b, 0x08, 0x00, 0x00, 0x09, 0x6e, 0x88, 0x02, 0xff, 0x6c, 0x90, 0xbd, 0x4f, 0xc3, 0x40,
0x0c, 0xc5, 0x15, 0xda, 0x7c, 0xe0, 0x6c, 0x16, 0xaa, 0x0c, 0x53, 0xd4, 0x89, 0x29, 0x95, 0x40,
0x42, 0xcc, 0xec, 0x5d, 0x3a, 0xb2, 0x99, 0xc4, 0x22, 0x27, 0x48, 0x2e, 0xba, 0x3b, 0x40, 0xfc,
0xe3, 0xcc, 0x5c, 0xdc, 0xaf, 0x0c, 0x1d, 0x22, 0xbd, 0xf7, 0x7e, 0x79, 0x3e, 0xd9, 0x70, 0xdb,
0xf1, 0x68, 0x36, 0x4d, 0xc7, 0x2e, 0x6c, 0x7a, 0x09, 0xdc, 0x72, 0xe0, 0x7a, 0x74, 0x36, 0x58,
0x84, 0x09, 0xd5, 0x8a, 0xd6, 0x4f, 0x00, 0x5b, 0x36, 0x43, 0x88, 0x9f, 0x38, 0x44, 0x58, 0x0e,
0xdc, 0x0b, 0x25, 0x55, 0x72, 0x7f, 0xbd, 0x53, 0x8d, 0x37, 0x90, 0x4a, 0xcf, 0xe6, 0x93, 0xae,
0x34, 0xdc, 0x9b, 0xf5, 0x5f, 0x02, 0xc5, 0xf6, 0x30, 0xf6, 0x62, 0x2d, 0x66, 0x9d, 0x8d, 0xd9,
0xbe, 0xa5, 0x1a, 0x09, 0x72, 0x6f, 0xbf, 0x5c, 0x23, 0x9e, 0x16, 0xd5, 0x22, 0xc6, 0x47, 0x3b,
0x91, 0x6f, 0x71, 0xde, 0xd8, 0x81, 0x96, 0x5a, 0x38, 0x5a, 0xac, 0xa0, 0x6c, 0xc5, 0x37, 0xce,
0x8c, 0x61, 0xa2, 0xa9, 0xd2, 0x79, 0x84, 0x77, 0x50, 0x7c, 0xc8, 0xef, 0x8f, 0x75, 0xad, 0xa7,
0x4c, 0xc7, 0x9e, 0x3c, 0x3e, 0x43, 0xd9, 0x9f, 0xd6, 0xf3, 0x94, 0x47, 0x5c, 0x3e, 0xac, 0xea,
0xf3, 0x01, 0xea, 0xf3, 0xf6, 0xbb, 0xf9, 0xaf, 0xb8, 0x82, 0x4c, 0x86, 0xf7, 0xa8, 0xa9, 0xd0,
0x27, 0x0f, 0xee, 0x25, 0x7f, 0x4d, 0xb5, 0xf8, 0x96, 0xe9, 0x31, 0x1f, 0xff, 0x03, 0x00, 0x00,
0xff, 0xff, 0x6f, 0x4a, 0x7b, 0xd0, 0x69, 0x01, 0x00, 0x00,
}

Write Preview
Loading…
Cancel
Save