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
-
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 thewerf.yaml
project
field settings. See more info in the chart article. -
Next it is required to generate
.helm/Chart.lock
usingwerf 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. -
.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. Therepository
can be an alias. The alias must start withalias:
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:
- Use
werf helm dependency list
to check dependencies and their statuses. - Use
werf helm dependency update
to update.helm/charts
based on the contents of.helm/Chart.yaml
. - Use
werf helm dependency build
to update.helm/charts
based on the.helm/Chart.lock
file.
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:
- Use
werf helm repo add
to add Chart Repository. - Use
werf helm repo index
. - Use
werf helm repo list
to list existing Chart Repositories. - Use
werf helm repo remove
to remove Chart Repository. - Use
werf helm repo update
to update local Chart Repositories indexes.
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.