Subchart is a helm chart that included into the current chart as a dependency. werf allows usage of subcharts the same way as helm. The chart can include arbitrary number of subcharts. Usage of werf project itself as a subchart in another werf project is not supported for now.

Subcharts are placed in the directory .helm/charts/SUBCHART_DIR. Each subchart in the SUBCHART_DIR is a chart by itself with the similar files structure (which can also have own recursive subcharts).

During deploy process werf will render, create and track all resources of all subcharts.

Enable subchart for your project

  1. Let’s include a redis as a dependency for our werf chart using .helm/Chart.yaml file:

     # .helm/Chart.yaml
 apiVersion: v2
 dependencies:
   - name: redis
     version: "12.7.4"
     repository: "https://charts.bitnami.com/bitnami"

    NOTE It is not required to define full Chart.yaml with name and version fields as for the standard helm. werf will autogenerate chart name and version based on the werf.yaml project field settings. See more info in the chart article.

  2. Next it is required to generate .helm/Chart.lock using werf helm dependency update command from the root of the project:

     werf helm dependency update .helm

    This command will generate .helm/Chart.lock file as well as download all dependencies into the .helm/charts directory.

  3. .helm/Chart.lock file should be committed into the git repository, while .helm/charts could be added to the .gitignore.

Later during deploy process (with werf converge command or werf bundle apply command), or during templates rendering (with werf render command) werf will automatically download all dependencies specified in the lock file .helm/Chart.lock.

NOTE .helm/Chart.lock file must be committed into the git repo, more info in the giterminism article.

Dependencies configuration

Let’s describe format of the .helm/Chart.yaml dependencies.

  • The name should be the name of a chart, where that name must match the name in that chart’s ‘Chart.yaml’ file.
  • The version field should contain a semantic version or version range.
  • The repository URL should point to a Chart Repository. Helm expects that by appending /index.yaml to the URL, it should be able to retrieve the chart repository’s index. The repository can be an alias. The alias must start with alias: or @.

The .helm/Chart.lock file lists the exact versions of immediate dependencies and their dependencies and so forth.

The werf helm dependency commands operate on that file, making it easy to synchronize between the desired dependencies and the actual dependencies stored in the charts directory:

All Chart Repositories that are used in .helm/Chart.yaml should be configured on the system. The werf helm repo commands can be used to interact with Chart Repositories:

werf is compatible with Helm settings, so by default werf helm dependency and werf helm repo commands use settings from helm home folder, ~/.helm. But you can change it with --helm-home option. If you do not have helm home folder or want to create another one use werf helm repo init command to initialize necessary settings and configure default Chart Repositories.

Passing values to subcharts

To pass values from parent chart to subchart called mysubchart user must define following values in the parent chart:

mysubchart:
  key1:
    key2:
    - key3: value

In the mysubchart these values should be specified without mysubchart key:

{{ .Values.key1.key2[0].key3 }}

Global values defined by the special toplevel values key global will also be available in the subcharts:

global:
  database:
    mysql:
      user: user
      password: password

In the subcharts these values should be specified as always:

{{ .Values.global.database.mysql.user }}

Only values by keys mysubchart and global will be available in the subchart mysubchart.

NOTE secret-values.yaml files from subcharts will not be used during deploy process. Although secret values from main chart and additional secret values from cli params --secret-values will be available in the .Values as usually.

Mapping values from parent chart to subcharts

If you want to pass the values available only in the parent chart to subcharts, then there is an export-values directive which mimics (with a few differences) functionality of import-values, but instead of passing values from the subchart to the parent chart it does the opposite: it passes values down from the parent chart to the subchart. Usage is as follows:

# .helm/Chart.yaml
apiVersion: v2
dependencies:
  - name: backend
    version: 1.0.0
    export-values:
    - parent: werf.image.backend
      child: backend.image

This will pass to the subchart whatever will be in the parent chart at .Values.werf.image.backend path. In our particular case this will be the string with the repo, image and tag of the image backend, defined in werf.yaml, e.g. example.org/backend:<image_tag>. In the subchart you can access the result with .Values.backend.image:

# .helm/charts/backend/app.yaml
...
spec:
  template:
    spec:
      containers:
      - name: backend
        image: {{ .Values.backend.image }}  # Will result in: `image: example.org/backend:<image_tag>`

Unlike YAML-anchors, export-values will also work with dynamically set values (werf service values), passed via command-line values (--set and similar) and secret values.

There is an alternative short form of export-values, which will only work for maps:

    export-values:
    - "someMap"

Which is an equivalent to:

    export-values:
    - parent: exports.somemap
      child: .

This will export all the keys found in .Values.exports.somemap to the root of subchart values.

Obsolete requirements.yaml and requirements.lock

An older way of storing dependencies in the .helm/requirements.yaml and .helm/requirements.lock files is also supported by the werf, but it is recommended to use .helm/Chart.yaml and .helm/Chart.lock instead.