https://helm.sh/docs/topics/charts/

Chart

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 the Kubernetes equivalent of a Homebrew formula, an Apt dpkg, or a Yum RPM file.

Directory structure

wordpress/
  Chart.yaml          # A YAML file containing information about the chart
  LICENSE             # OPTIONAL: A plain text file containing the license for the chart
  README.md           # OPTIONAL: A human-readable README file
  values.yaml         # The default configuration values for this chart
  values.schema.json  # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file
  charts/             # A directory containing any charts upon which this chart depends.
  crds/               # Custom Resource Definitions
  templates/          # A directory of templates that, when combined with values,
                      # will generate valid Kubernetes manifest files.
  templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes

Pull:

helm pull chartrepo/chartname

Get info:

helm show chart bitnami/mysql

Install:

$ helm install bitnami/mysql --generate-name
NAME: mysql-1612624192
LAST DEPLOYED: Sat Feb  6 16:09:56 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES: ...

List installed:

1

helm list

Chart Types

The type field defines the type of chart. There are two types: application and library. Application is the default type and it is the standard chart which can be operated on fully. The library chart provides utilities or functions for the chart builder. A library chart differs from an application chart because it is not installable and usually doesn’t contain any resource objects.

Importing Child Values via dependencies

In some cases it is desirable to allow a child chart’s values to propagate to the parent chart and be shared as common defaults. An additional benefit of using the exports format is that it will enable future tooling to introspect user-settable values.

The keys containing the values to be imported can be specified in the parent chart’s dependencies in the field import-values using a YAML list. Each item in the list is a key which is imported from the child chart’s exports field.

To import values not contained in the exports key, use the child-parent format. Examples of both formats are described below.

Using the exports format

If a child chart’s values.yaml file contains an exports field at the root, its contents may be imported directly into the parent’s values by specifying the keys to import as in the example below:

1
2
3
4
5
6
7
8

# parent's Chart.yaml file

dependencies:
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    import-values:
      - data

1
2
3
4
5

# child's values.yaml file

exports:
  data:
    myint: 99

Using the child-parent format

To access values that are not contained in the exports key of the child chart’s values, you will need to specify the source key of the values to be imported (child) and the destination path in the parent chart’s values (parent).

The import-values in the example below instructs Helm to take any values found at child: path and copy them to the parent’s values at the path specified in parent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# parent's Chart.yaml file

dependencies:
  - name: subchart1
    repository: http://localhost:10191
    version: 0.1.0
    ...
    import-values:
      - child: default.data
        parent: myimports

In the above example, values found at default.data in the subchart1’s values will be imported to the myimports key in the parent chart’s values as detailed below:

1
2
3
4
5
6

# parent's values.yaml file

myimports:
  myint: 0
  mybool: false
  mystring: "helm rocks!"

1
2
3
4
5
6

# subchart1's values.yaml file

default:
  data:
    myint: 999
    mybool: true

The parent chart’s resulting values would be:

1
2
3
4
5
6

# parent's final values

myimports:
  myint: 999
  mybool: true
  mystring: "helm rocks!"

Operational aspects of using dependencies

The above sections explain how to specify chart dependencies, but how does this affect chart installation using helm install and helm upgrade?

Suppose that a chart named “A” creates the following Kubernetes objects

• namespace “A-Namespace”
• statefulset “A-StatefulSet”
• service “A-Service”

Furthermore, A is dependent on chart B that creates objects

• namespace “B-Namespace”
• replicaset “B-ReplicaSet”
• service “B-Service”

After installation/upgrade of chart A a single Helm release is created/modified. The release will create/update all of the above Kubernetes objects in the following order:

• A-Namespace
• B-Namespace
• A-Service
• B-Service
• B-ReplicaSet
• A-StatefulSet

This is because when Helm installs/upgrades charts, the Kubernetes objects from the charts and all its dependencies are

• aggregated into a single set; then
• sorted by type followed by name; and then
• created/updated in that order.

Hence a single release is created with all the objects for the chart and its dependencies.

The install order of Kubernetes types is given by the enumeration InstallOrder in kind_sorter.go (see the Helm source file).

Templates and Values

Helm Chart templates are written in the Go template language, with the addition of 50 or so add-on template functions from the Sprig library and a few other specialized functions.

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 provided on the command line with helm install.

When a user supplies custom values, these values will override the values in the chart’s values.yaml file.

Predefined Values

Values that are supplied via a values.yaml file (or via the --set flag) are accessible from the .Values object in a template. But there are other pre-defined pieces of data you can access in your templates.

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.Namespace: The namespace the chart was released to.
• Release.Service: The service that conducted the release.
• Release.IsUpgrade: This is set to true if the current operation is an upgrade or rollback.
• Release.IsInstall: This is set to true if the current operation is an install.
• Chart: The contents of the Chart.yaml. Thus, the chart version is obtainable as Chart.Version and the maintainers are in Chart.Maintainers.
• Files: A map-like object containing all non-special files in the chart. This will not give you access to templates, but will give you access to additional files that are present (unless they are excluded using .helmignore). Files can be accessed using {{ index .Files "file.name" }} or using the {{.Files.Get name }} function. You can also access the contents of the file as []byte using {{ .Files.GetBytes }}
• Capabilities: A map-like object that contains information about the versions of Kubernetes ({{ .Capabilities.KubeVersion }}) and the supported Kubernetes API versions ({{ .Capabilities.APIVersions.Has "batch/v1" }})

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:

1
2
3
4
5
6
7
8

title: "My WordPress Site" # Sent to the WordPress template

mysql:
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  port: 8080 # Passed to Apache

Charts at a higher level have access to all of the variables defined beneath. So the WordPress chart can access the MySQL password as .Values.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.

Global Values

As of 2.0.0-Alpha.2, Helm supports special “global” value. Consider this modified version of the previous example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

title: "My WordPress Site" # Sent to the WordPress template

global:
  app: MyWordPress

mysql:
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  port: 8080 # Passed to Apache

Custom Resource Definitions (CRDs)

Kubernetes provides a mechanism for declaring new types of Kubernetes objects. Using CustomResourceDefinitions (CRDs), Kubernetes developers can declare custom resource types.

In Helm 3, CRDs are treated as a special kind of object. They are installed before the rest of the chart, and are subject to some limitations.

CRD YAML files should be placed in the crds/ directory inside of a chart. Multiple CRDs (separated by YAML start and end markers) may be placed in the same file. Helm will attempt to load all of the files in the CRD directory into Kubernetes.

CRD files cannot be templated. They must be plain YAML documents.

When Helm installs a new chart, it will upload the CRDs, pause until the CRDs are made available by the API server, and then start the template engine, render the rest of the chart, and upload it to Kubernetes. Because of this ordering, CRD information is available in the .Capabilities object in Helm templates, and Helm templates may create new instances of objects that were declared in CRDs.

Using Helm to Manage Charts

The helm tool has several commands for working with charts.

It can create a new chart for you:

$ helm create mychart
Created mychart/

Once you have edited a chart, helm can package it into a chart archive for you:

$ helm package mychart
Archived mychart-0.1.-.tgz

You can also use helm to help you find issues with your chart’s formatting or information:

$ helm lint mychart
No issues found