Chart Dependencies

In Helm, one chart may depend on any number of other charts.These dependencies can be dynamically linked through the requirements.yamlfile or brought in to the charts/ directory and managed manually.

Although manually managing your dependencies has a few advantages some teams need,the preferred method of declaring dependencies is by using arequirements.yaml file inside of your chart.

Note: The dependencies: section of the Chart.yaml from HelmClassic has been completely removed.

Managing Dependencies with requirements.yaml

A requirements.yaml file is a simple file for listing yourdependencies.

  1. dependencies:
  2.   - name: apache
  3.     version: 1.2.3
  4.     repository: http://example.com/charts
  5.   - name: mysql
  6.     version: 3.2.1
  7.     repository: http://another.example.com/charts
  • The name field is the name of the chart you want.
  • The version field is the version of the chart you want.
  • The repository field is the full URL to the chart repository. Notethat you must also use helm repo add to add that repo locally.Once you have a dependencies file, you can run helm dependency updateand it will use your dependency file to download all the specifiedcharts into your charts/ directory for you.
  1. $ helm dep up foochart
  2. Hang tight while we grab the latest from your chart repositories...
  3. ...Successfully got an update from the "local" chart repository
  4. ...Successfully got an update from the "stable" chart repository
  5. ...Successfully got an update from the "example" chart repository
  6. ...Successfully got an update from the "another" chart repository
  7. Update Complete.
  8. Saving 2 charts
  9. Downloading apache from repo http://example.com/charts
  10. Downloading mysql from repo http://another.example.com/charts

When helm dependency update retrieves charts, it will store them aschart archives in the charts/ directory. So for the example above, onewould expect to see the following files in the charts directory:

  1. charts/
  2.   apache-1.2.3.tgz
  3.   mysql-3.2.1.tgz

Managing charts with requirements.yaml is a good way to easily keepcharts updated, and also share requirements information throughout ateam.

Alias field in requirements.yaml

In addition to the other fields above, each requirements entry may containthe optional field alias.

Adding an alias for a dependency chart would puta chart in dependencies using alias as name of new dependency.

One can use alias in cases where they need to access a chartwith other name(s).

  1. # parentchart/requirements.yaml
  2. dependencies:
  3.   - name: subchart
  4.     repository: http://localhost:10191
  5.     version: 0.1.0
  6.     alias: new-subchart-1
  7.   - name: subchart
  8.     repository: http://localhost:10191
  9.     version: 0.1.0
  10.     alias: new-subchart-2
  11.   - name: subchart
  12.     repository: http://localhost:10191
  13.     version: 0.1.0

In the above example we will get 3 dependencies in all for parentchart

  1. subchart
  2. new-subchart-1
  3. new-subchart-2

The manual way of achieving this is by copy/pasting the same chart in thecharts/ directory multiple times with different names.

Tags and Condition fields in requirements.yaml

In addition to the other fields above, each requirements entry may containthe optional fields tags and condition.

All charts are loaded by default. If tags or condition fields are present,they will be evaluated and used to control loading for the chart(s) they are applied to.

Condition - The condition field holds one or more YAML paths (delimited by commas).If this path exists in the parent’s values and resolves to a boolean value,the chart will be enabled or disabled based on that boolean value. Only the firstvalid path found in the list is evaluated and if no paths exist then the conditionhas no effect. For multiple level dependencies the condition is prependend by thepath to the parent chart.

Tags - The tags field is a YAML list of labels to associate with this chart.In the top parent’s values, all charts with tags can be enabled or disabled byspecifying the tag and a boolean value.

  1. # parentchart/requirements.yaml
  2. dependencies:
  3.   - name: subchart1
  4.     repository: http://localhost:10191
  5.     version: 0.1.0
  6.     condition: subchart1.enabled
  7.     tags:
  8.       - front-end
  9.       - subchart1
  11.   - name: subchart2
  12.     repository: http://localhost:10191
  13.     version: 0.1.0
  14.     condition: subchart2.enabled
  15.     tags:
  16.       - back-end
  17.       - subchart2
  1. # subchart2/requirements.yaml
  2. dependencies:
  3.   - name: subsubchart
  4.     repository: http://localhost:10191
  5.     version: 0.1.0
  6.     condition: subsubchart.enabled
  1. # parentchart/values.yaml
  3. subchart1:
  4.   enabled: true
  5. subchart2:
  6.   subsubchart:
  7.     enabled: false
  8. tags:
  9.   front-end: false
  10.   back-end: true

In the above example all charts with the tag front-end would be disabled but since thesubchart1.enabled path evaluates to ‘true’ in the parent’s values, the condition will override thefront-end tag and subchart1 will be enabled.

Since subchart2 is tagged with back-end and that tag evaluates to true, subchart2 will beenabled. Also note that although subchart2 has a condition specified in requirements.yaml, thereis no corresponding path and value in the parent’s values so that condition has no effect.

subsubchart is disabled by default but can be enabled by setting subchart2.subsubchart.enabled=true.Hint: disabling subchart2 via tag will also disable all sub-charts (even if overriding the value subchart2.subsubchart.enabled=true).

Using the CLI with Tags and Conditions

The —set parameter can be used as usual to alter tag and condition values.

  1. helm install --set tags.front-end=true --set subchart2.enabled=false
Tags and Condition Resolution
  • Conditions (when set in values) always override tags.
  • The first condition path that exists wins and subsequent ones for that chart are ignored.
  • Tags are evaluated as ‘if any of the chart’s tags are true then enable the chart’.
  • Tags and conditions values must be set in the top parent’s values.
  • The tags: key in values must be a top level key. Globals and nested tags: tablesare not currently supported.

Importing Child Values via requirements.yaml

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

The keys containing the values to be imported can be specified in the parent chart’s requirements.yaml fileusing 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 importeddirectly into the parent’s values by specifying the keys to import as in the example below:

  1. # parent's requirements.yaml file
  2.     ...
  3.     import-values:
  4.       - data
  1. # child's values.yaml file
  2. ...
  3. exports:
  4.   data:
  5.     myint: 99

Since we are specifying the key data in our import list, Helm looks in the exports field of the childchart for data key and imports its contents.

The final parent values would contain our exported field:

  1. # parent's values file
  2. ...
  3. myint: 99

Please note the parent key data is not contained in the parent’s final values. If you need to specify theparent key, use the ‘child-parent’ format.

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 tospecify the source key of the values to be imported (child) and the destination path in the parent chart’svalues (parent).

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

  1. # parent's requirements.yaml file
  2. dependencies:
  3.   - name: subchart1
  4.     repository: http://localhost:10191
  5.     version: 0.1.0
  6.     ...
  7.     import-values:
  8.       - child: default.data
  9.         parent: myimports

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

  1. # parent's values.yaml file
  3. myimports:
  4.   myint: 0
  5.   mybool: false
  6.   mystring: "helm rocks!"
  1. # subchart1's values.yaml file
  3. default:
  4.   data:
  5.     myint: 999
  6.     mybool: true

The parent chart’s resulting values would be:

  1. # parent's final values
  3. myimports:
  4.   myint: 999
  5.   mybool: true
  6.   mystring: "helm rocks!"

The parent’s final values now contains the myint and mybool fields imported from subchart1.

Managing Dependencies manually via the charts/ directory

If more control over dependencies is desired, these dependencies canbe expressed explicitly by copying the dependency charts into thecharts/ directory.

A dependency can be either a chart archive (foo-1.2.3.tgz) or anunpacked chart directory. But its name cannot start with _ or ..Such files are ignored by the chart loader.

For example, if the WordPress chart depends on the Apache chart, theApache chart (of the correct version) is supplied in the WordPresschart’s charts/ directory:

  1. wordpress:
  2.   Chart.yaml
  3.   requirements.yaml
  4.   # ...
  5.   charts/
  6.     apache/
  7.       Chart.yaml
  8.       # ...
  9.     mysql/
  10.       Chart.yaml
  11.       # ...

The example above shows how the WordPress chart expresses its dependencyon Apache and MySQL by including those charts inside of its charts/directory.

TIP:To drop a dependency into your charts/ directory, use thehelm fetch command

Operational aspects of using dependencies

The above sections explain how to specify chart dependencies, but how does this affectchart 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 willcreate/update all of the above Kubernetes objects in the following order:

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

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).