diff --git a/_proto/hapi/chart/metadata.proto b/_proto/hapi/chart/metadata.proto index aeb92e7b8..c8b5e75c3 100644 --- a/_proto/hapi/chart/metadata.proto +++ b/_proto/hapi/chart/metadata.proto @@ -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; } diff --git a/docs/charts.md b/docs/charts.md index 17a779fc1..5055cbf4b 100644 --- a/docs/charts.md +++ b/docs/charts.md @@ -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. diff --git a/pkg/proto/hapi/chart/metadata.pb.go b/pkg/proto/hapi/chart/metadata.pb.go index ceaa7914b..ee020f5d2 100644 --- a/pkg/proto/hapi/chart/metadata.pb.go +++ b/pkg/proto/hapi/chart/metadata.pb.go @@ -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, }