Helm Specifications

Helm charts serve as a packaging format. A chart is a collection of files that describe a related set of Kubernetes resources. For more information, see the Helm documentation.

Structure

All related files of a chart is stored in a directory which generally contains:

  1. chartname/
  2.   Chart.yaml          # A YAML file containing basic information about the chart, such as version and name.
  3.   LICENSE             # (Optional) A plain text file containing the license for the chart.
  4.   README.md           # (Optional) The description of the app and how-to guide.
  5.   values.yaml         # The default configuration values for this chart.
  6.   values.schema.json  # (Optional) A JSON Schema for imposing a structure on the values.yaml file.
  7.   charts/             # A directory containing any charts upon which this chart depends.
  8.   crds/               # Custom Resource Definitions.
  9.   templates/          # A directory of templates that will generate valid Kubernetes configuration files with corresponding values provided.
  10.   templates/NOTES.txt # (Optional) A plain text file with usage notes.

Chart.yaml File

You must provide the chart.yaml file for a chart. Here is an example of the file with explanations for each field.

  1. apiVersion: (Required) The chart API version. 
  2. name: (Required) The name of the chart.
  3. version: (Required) The version, following the SemVer 2 standard. 
  4. kubeVersion: (Optional) The compatible Kubernetes version, following the SemVer 2 standard.
  5. description: (Optional) A single-sentence description of the app.
  6. type: (Optional) The type of the chart.
  7. keywords:
  8.   - (Optional) A list of keywords about the app.
  9. home: (Optional) The URL of the app.
  10. sources:
  11.   - (Optional) A list of URLs to source code for this app.
  12. dependencies: (Optional) A list of the chart requirements.
  13.   - name: The name of the chart, such as nginx.
  14.     version: The version of the chart, such as "1.2.3".
  15.     repository: The repository URL ("https://example.com/charts") or alias ("@repo-name").
  16.     condition: (Optional) A yaml path that resolves to a boolean, used for enabling/disabling charts (e.g. subchart1.enabled ).
  17.     tags: (Optional)
  18.       - Tags can be used to group charts for enabling/disabling together.
  19.     import-values: (Optional)
  20.       - ImportValues holds the mapping of source values to parent key to be imported. Each item can be a string or pair of child/parent sublist items.
  21.     alias: (Optional) Alias to be used for the chart. It is useful when you have to add the same chart multiple times.
  22. maintainers: (Optional)
  23.   - name: (Required) The maintainer name.
  24.     email: (Optional) The maintainer email.
  25.     url: (Optional) A URL for the maintainer.
  26. icon: (Optional) A URL to an SVG or PNG image to be used as an icon.
  27. appVersion: (Optional) The app version. This needn't be SemVer.
  28. deprecated: (Optional, boolean) Whether this chart is deprecated.
  29. annotations:
  30.   example: (Optional) A list of annotations keyed by name.

Note

  • The field dependencies is used to define chart dependencies which were located in a separate file requirements.yaml for v1 charts. For more information, see Chart Dependencies.
  • The field type is used to define the type of chart. Allowed values are application and library. For more information, see Chart Types.

Values.yaml and Templates

Written in the Go template language, Helm chart templates are stored in the templates folder of a chart. There are two ways to provide values for the templates:

  1. Make a values.yaml file inside of a chart with default values that can be referenced.
  2. Make a YAML file that contains necessary values and use the file through the command line with helm install.

Here is an example of the template in the templates folder.

  1. apiVersion: v1
  2. kind: ReplicationController
  3. metadata:
  4.   name: deis-database
  5.   namespace: deis
  6.   labels:
  7.     app.kubernetes.io/managed-by: deis
  8. spec:
  9.   replicas: 1
  10.   selector:
  11.     app.kubernetes.io/name: deis-database
  12.   template:
  13.     metadata:
  14.       labels:
  15.         app.kubernetes.io/name: deis-database
  16.     spec:
  17.       serviceAccount: deis-database
  18.       containers:
  19.         - name: deis-database
  20.           image: {{.Values.imageRegistry}}/postgres:{{.Values.dockerTag}}
  21.           imagePullPolicy: {{.Values.pullPolicy}}
  22.           ports:
  23.             - containerPort: 5432
  24.           env:
  25.             - name: DATABASE_STORAGE
  26.               value: {{default "minio" .Values.storage}}

The above example defines a ReplicationController template in Kubernetes. There are some values referenced in it which are defined in values.yaml.

  • imageRegistry: The Docker image registry.
  • dockerTag: The Docker image tag.
  • pullPolicy: The image pulling policy.
  • storage: The storage backend. It defaults to minio.

An example values.yaml file:

  1. imageRegistry: "quay.io/deis"
  2. dockerTag: "latest"
  3. pullPolicy: "Always"
  4. storage: "s3"

Reference

Helm Documentation

Charts