This part of the Best Practices Guide explains general conventions.
## Chart Names
Chart names should be lower case letters and numbers. Words _may_ be separated with dashes (-):
Examples:
```
drupal
nginx-lego
aws-cluster-autoscaler
```
Neither uppercase letters nor underscores should be used in chart names. Dots should not be used in chart names.
The directory that contains a chart MUST have the same name as the chart. Thus, the chart `nginx-lego` MUST be created in a directory called `nginx-lego/`. This is not merely a stylistic detail, but a requirement of the Helm Chart format.
## Version Numbers
Wherever possible, Helm uses [SemVer 2](http://semver.org) to represent version numbers. (Note that Docker image tags do not necessarily follow SemVer, and are thus considered an unfortunate exception to the rule.)
When SemVer versions are stored in Kubernetes labels, we conventionally alter the `+` character to an `_` character, as labels do not allow the `+` sign as a value.
## Formatting YAML
YAML files should be indented using _two spaces_ (and never tabs).
## Usage of the Words Helm, Tiller, and Chart
There are a few small conventions followed for using the words Helm, helm, Tiller, and tiller.
- Helm refers to the project, and is often used as an umbrella term
-`helm` refers to the client-side command
- Tiller is the proper name of the backend
-`tiller` is the name of the binary run on the backend
- The term 'chart' does not need to be capitalized, as it is not a proper noun.
When in doubt, use _Helm_ (with an uppercase 'H').
This part of the Best Practices Guide discusses the best practices for using
labels and annotations in your chart.
## Is it a Label or an Annotation?
An item of metadata should be a label under the following conditions:
- It is used by Kubernetes to identify this resource
- It is useful to expose to operators for the purpose of querying the system.
For example, we suggest using `chart: NAME-VERSION` as a label so that operators
can conveniently find all of the instances of a particular chart to use.
If an item of metadata is not used for querying, it should be set as an annotation
instead.
Helm hooks are always annotations.
## Standard Labels
The following table defines common labels that Helm charts use. Helm itself never requires that a particular label be present. Labels that are marked REC
are recommended, and _should_ be placed onto a chart for global consistency. Those marked OPT are optional. These are idiomatic or commonly in use, but are not relied upon frequently for operational purposes.
Name|Status|Description
-----|------|----------
heritage | REC | This should always be set to `Tiller`. It is for finding all things managed by Tiller.
release | REC | This should be the `{{ .Release.Name }}`.
chart | REC | This should be the chart name and version: `{{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}`.
app | OPT | This should be the app name, reflecting the entire app. Often the chart's `{{ .Chart.Name }}` is used for this. This is used by many Kubernetes manifests, and is not Helm-specific.
component | OPT | This is a common label for marking the different roles that pieces may play in an application. For example, `component: frontend`
This part of the Best Practices Guide discusses formatting the Pod and PodTemplate
portions in chart manifests.
The following (non-exhaustive) list of resources use PodTemplates:
- Deployment
- ReplicationController
- ReplicaSet
- DaemonSet
- StatefulSet
## Images
A container image should use a fixed tag or the SHA of the image. It should not use the tags `latest`, `head`, `canary`, or other tags that are designed to be "floating".
Images _may_ be defined in the `values.yaml` file to make it easy to swap out images.
```
image: {{ .Values.redisImage | quote }}
```
An image and a tag _may_ be defined in `values.yaml` as two separate fields:
This section of the guide covers best practices for `requirements.yaml` files.
## Versions
Where possible, use version ranges instead of pinning to an exact version. The suggested default is to use a patch-level version match:
```yaml
version:^1.2.0
```
This will match version 1.2.0 and any patches to that release (1.2.1, 1.2.999, and so on)
### Repository URLs
Where possible, use `https://` repository URLs, followed by `http://` URLs.
File URLs (`file://...`) are considered a "special case" for charts that are assembled by a fixed deployment pipeline. Charts that use `file://` in a `requirements.yaml` file are not allowed in the official Helm repository.
## Conditions and Tags
Conditions or tags should be added to any dependencies that _are optional_.
The preferred form of a condition is:
```yaml
condition:somechart.enabled
```
Where `somechart` is the chart name of the dependency.
When multiple subcharts (dependencies) together provide an optional or swappable feature, those charts should share the same tags.
For example, if both `nginx` and `memcached` together provided performance optimizations for the main app in the chart, and were required to both be present when that feature is enabled, then they might both have a
tags section like this:
```
tags:
- webaccelerator
```
This allows a user to turn that feature on and off with one tag.
This part of the best practices guide covers using values. In this part of the
guide, we provide recommendations on how you should structure and use your
values, with focus on designing a chart's `values.yaml` file.
## Naming Conventions
Variables names should begin with a lowercase letter, and words should be
separated with camelcase:
Correct:
```yaml
chicken:true
chickenNoodleSoup:true
```
Incorrect:
```yaml
Chicken:true# initial caps may conflict with built-ins
chicken-noodle-soup:true# do not use hyphens in the name
```
Note that all of Helm's built-in variables begin with an uppercase letter to
easily distinguish them from user-defined values: `.Release.Name`,
`.Capabilities.KubeVersion`.
## Flat or Nested Values
YAML is a flexible format, and values may be nested deeply or flattened.
Nested:
```yaml
server:
name:nginx
port:80
```
Flat:
```yaml
serverName:nginx
serverPort:80
```
In most cases, flat should be favored over nested. The reason for this is that
it is simpler for template developers and users.
For optimal safety, a nested value must be checked at every level:
```
{{ if .Values.server }}
{{ default "none" .Values.server.name }}
{{ end }}
```
For every layer of nesting, an existence check must be done. But for flat
configuration, such checks can be skipped, making the template easier to read
and use.
```
{{ default "none" .Values.serverName }}
```
When there are a large number of related variables, and at least one of them
is non-optional, nested values may be used to improve readability.
## Make Types Clear
YAML's type coercion rules are sometimes counterintuitive. For example,
`foo: false` is not the same as `foo: "false"`. Large integers like `foo: 12345678`
will get converted to scientific notation in some cases.
The easiest way to avoid type conversion errors is to be explicit about strings,
and implicit about everything else. Or, in short, _quote all strings_.
Often, to avoid the integer casting issues, it is advantageous to store your
integers as strings as well, and use `{{ int $value }}` in the template to convert
from a string back to an integer.
In most cases, explicit type tags are respected, so `foo: !!string 1234` should
treat `1234` as a string. _However_, the YAML parser consumes tags, so the type
data is lost after one parse.
## Consider How Users Will Use Your Values
There are three potential sources of values:
- A chart's `values.yaml` file
- A values file supplied by `helm install -f` or `helm upgrade -f`
- The values passed to a `--set` flag on `helm install` or `helm upgrade`
When designing the structure of your values, keep in mind that users of your
chart may want to override them via either the `-f` flag or with the `--set`
option.
Since `--set` is more limited in expressiveness, the first guidelines for writing
your `values.yaml` file is _make it easy to override from `--set`_.
For this reason, it's often better to structure your values file using maps.
Difficult to use with `--set`:
```yaml
servers:
-name:foo
port:80
-name:bar
port:81
```
Easy to use:
```yaml
servers:
foo:
port:80
bar:
port:81
```
## Document 'values.yaml'
Every defined property in 'values.yaml' should be documented. The documentation string should begin with the name of the property that it describes, and then give at least a one-sentence description.
Incorrect:
```
# the host name for the webserver
serverHost = example
serverPort = 9191
```
Correct:
```
# serverHost is the host name for the webserver
serverHost = example
# serverPort is the HTTP listener port for the webserver
serverPort = 9191
```
Beginning each comment with the name of the parameter it documents makes it easy to grep out documentation, and will enable documentation tools to reliably correlate doc strings with the parameters they describe.
