Parameterization basics
The contents of the $.Values dictionary can be used to parameterize templates. Each chart has its own $.Values dictionary. The dictionary is compiled by merging parameters obtained from parameter files, command line options and other sources.
Below is a quick example of parameterization using values.yaml:
# values.yaml:
myparam: myvalue
# templates/example.yaml:
{{ $.Values.myparam }}
Output:
myvalue
And here is a more complex example:
# values.yaml:
myparams:
- value: original
# templates/example.yaml:
{{ (index $.Values.myparams 0).value }}
werf render --set myparams[0].value=overriden
Output:
overriden
Parameter sources and their priority
The $.Values dictionary is compiled by combining the parameters from the parameter sources in the following order, from the lowest priority to the highest:
values.yamlof the current chart.secret-values.yamlof the current chart (werf only).- The dictionary in
values.yamlof the parent chart, whose key is the alias or name of the current chart. - The dictionary in
secret-values.yamlof the parent chart (werf only), whose key is the alias or name of the current chart. - Parameter files stored in the
WERF_VALUES_*variable. - Parameter files set by the
--valuesoption. - Secret parameter files stored in the
WERF_SECRET_VALUES_*variable (werf only). - Secret parameter files set by the
--secret-valuesoption (werf only). - Parameters stored in the
WERF_SET_JSON_*variable. - Parameters set by the
--set-jsonoption. - Parameters stored in the
WERF_SET_*variable. - Parameters set by the
--setoption. - Parameters stored in the
WERF_SET_STRING_*variable. - Parameters set by the
--set-stringoption. - Parameters in the set files stored in the
WERF_SET_FILE_*variable. - Parameters in the set files set by the
--set-fileoption. - Parameters stored in the
WERF_SET_LITERAL_*variable. - Parameters set by the
--set-literaloption. - werf auxiliary parameters.
Sources 5–19 are passed to the main chart. The parameters of a dependent chart are taken from the dictionary whose key is the alias or name of the dependent chart, so --set mychild.myparam=value overrides myparam from values.yaml and secret-values.yaml of the mychild chart and from the mychild dictionary of the parent chart.
A chart published by werf bundle publish stores the publish-time parameters in .werf-data/, see Bundles. If the main chart contains .werf-data/, e.g. .helm holds an unpacked published chart, werf converge, werf plan, werf render and werf lint apply its parameters right after sources 1 and 2 of the main chart, before source 5: the parameters of --values, --secret-values and --set* at publish time, then the werf auxiliary parameters computed at publish time. The parameters from .werf-data/ of a werf-published dependent chart are applied right after sources 1 and 2 of that chart, so the parent chart overrides them.
The rules for combining parameters:
-
basic data types are overwritten;
-
lists are overwritten;
-
dictionaries are merged;
-
in case of a conflict, the parameters from the sources located higher in the list are overwritten by the parameters from the sources located lower in the list;
-
nullset by the--values,--secret-valuesor--set*options removes the value of the parameter with the same key that comes from the sources located higher in the list. -
nullset for the whole dictionary of a dependent chart, e.g.--set mychild=null, removes only the parameters of this chart that come from the--values,--secret-valuesand--set*options: the chart keeps the parameters from its ownvalues.yamlandsecret-values.yaml, from the dictionary invalues.yamlandsecret-values.yamlof the parent chart, and the parameters exported to it fromvalues.yamlof the parent chart, from the--set*options and from werf auxiliary parameters. If a parameter from the--set*options is exported to this chart, thenullhas no effect.
The export-values and import-values directives copy parameters between the parent chart and its dependent charts (see below) and do not form sources of their own: the copy is made within each of the following sources, and the priority of the copied parameter is the priority of the source it came from (from the lowest to the highest):
values.yamlof all charts andsecret-values.yamlof the dependent charts.secret-values.yamlof the main chart.- Parameter files (
WERF_VALUES_*and--values). - Secret parameter files (
WERF_SECRET_VALUES_*and--secret-values). - All
WERF_SET_*variables and--set*options. - werf auxiliary parameters.
All WERF_SET_* variables and --set* options form one source here, not separate sources 9–18 as in the list of sources for $.Values. Their order still applies when they set the same or an overlapping key, e.g. with --set-json 'myparam=1' --set myparam=2 the result is 2. With --set g.repo=A --set-string mychild.image.repository=B and g.repo exported to mychild.image.repository, the result is A: both options are in one source, where the exported parameter wins. Likewise, with --set-json 'mydict.myparam="A"' --set mychild.mydict.myparam=B and the mydict dictionary of mychild imported into mydict, the result is A: both options are in one source, where the parent chart’s own parameter wins, although --set has a higher priority than --set-json in the list of sources for $.Values.
-
export-valuescopies a parameter of the parent chart to a dependent chart. Within one source, the exported parameter overrides the parameter of the dependent chart with the same key. Across sources, the parameter from the source located lower in the list wins. For example,--set mychild.myparam=valueoverrides a parameter that is exported tomychild.myparamfromvalues.yamlof the parent chart, and a werf auxiliary parameter exported tomychild.image.repositoryoverridesmychild.image.repositoryfrom--values. If the exported parameter is itself exported to another dependent chart, e.g.parent: mysibling.myparam, it is copied after that export, regardless of the order of the dependencies inChart.yaml. If severalexport-valueswrite the same parameter, the one declared later wins. -
import-valuescopies a dictionary of a dependent chart to the parent chart. Within one source, the parent chart’s own parameter overrides the imported one with the same key. Across sources, the parameter from the source located lower in the list wins. For example, a dictionary imported from--set mychild.mydict.myparam=valueoverridesmydict.myparamfromvalues.yamlof the parent chart. As in Helm, imports are not chained: a dictionary imported into the parameters of another dependent chart, e.g.parent: mysibling.mydict, is not imported again by theimport-valuesof that chart.
A parameter that cannot be copied is skipped with a warning: a value other than a dictionary exported to the root of a dependent chart, or a value other than a dictionary or null imported from a dependent chart. An imported null is copied as null.
Parameterizing the chart
The chart can be parameterized using its parameter file:
# values.yaml:
myparam: myvalue
# templates/example.yaml:
{{ $.Values.myparam }}
Output:
myvalue
You can also add/override the chart parameters using command line arguments:
werf render --set myparam=overriden # or WERF_SET_MYPARAM=myparam=overriden werf render
werf render --set-string myparam=overriden # or WERF_SET_STRING_MYPARAM=myparam=overriden werf render
… as well as by additional parameter files:
# .helm/values-production.yaml:
myparam: overriden
werf render --values .helm/values-production.yaml # or WERF_VALUES_PROD=.helm/values-production.yaml werf render
… or by a secret parameter file of the main chart (werf only):
# .helm/secret-values.yaml:
myparam: <encrypted>
werf render
… or by additional secret parameter files of the main chart (werf only):
# .helm/secret-values-production.yaml:
myparam: <encrypted>
werf render --secret-values .helm/secret-values-production.yaml # or WERF_SECRET_VALUES_PROD=.helm/secret-values-production.yaml werf render
… or by set files:
# myparam.txt:
overriden
werf render --set-file myparam=myparam.txt # or WERF_SET_FILE_PROD=myparam=myparam.txt werf render
The output is the same:
overriden
Parameterizing dependent charts
A dependent chart can be parameterized both using its own parameter file and the parameter file of the parent chart.
In the example below, the parameters from the mychild dictionary in the values.yaml file of the myparent chart override the parameters in the values.yaml file of the mychild chart:
# Chart.yaml:
name: myparent
dependencies:
- name: mychild
# values.yaml:
mychild:
myparam: overriden
# charts/mychild/values.yaml:
myparam: original
# charts/mychild/templates/example.yaml:
{{ $.Values.myparam }}
Output:
overriden
Note that the dictionary in values.yaml of the parent chart that contains parameters for the dependent chart must have alias (if any) or name of the dependent chart as its name.
You can also add/override parameters of a dependent chart using command line arguments:
werf render --set mychild.myparam=overriden # or WERF_SET_MYPARAM=mychild.myparam=overriden werf render
werf render --set-string mychild.myparam=overriden # or WERF_SET_STRING_MYPARAM=mychild.myparam=overriden werf render
… as well as by additional parameter files:
# .helm/values-production.yaml:
mychild:
myparam: overriden
werf render --values .helm/values-production.yaml # or WERF_VALUES_PROD=.helm/values-production.yaml werf render
… or by a secret parameter file of the main chart (werf only):
# .helm/secret-values.yaml:
mychild:
myparam: <encrypted>
werf render
or by additional secret parameter files of the main chart (werf only):
# .helm/secret-values-production.yaml:
mychild:
myparam: <encrypted>
werf render --secret-values .helm/secret-values-production.yaml # or WERF_SECRET_VALUES_PROD=.helm/secret-values-production.yaml werf render
… or using set files:
# mychild-myparam.txt:
overriden
werf render --set-file mychild.myparam=mychild-myparam.txt # or WERF_SET_FILE_PROD=mychild.myparam=mychild-myparam.txt werf render
… or vie the export-values directive (werf only, not supported in charts with apiVersion: v3):
# Chart.yaml:
name: myparent
dependencies:
- name: mychild
export-values:
- parent: myparam
child: myparam
# values.yaml:
myparam: overriden
werf render
The output will be the same:
overriden
Using the dependent chart parameters in the parent chart
You can use the import-values directive in the parent chart to pass the parameters of the dependent chart to the parent one. Only dictionaries (or null) can be imported, and the parent chart’s own parameters override the imported ones:
# Chart.yaml:
name: myparent
dependencies:
- name: mychild
import-values:
- child: mydict
parent: mydict
# values.yaml:
mydict:
myparam1: original
# charts/mychild/values.yaml:
mydict:
myparam1: imported
myparam2: imported
# templates/example.yaml:
{{ $.Values.mydict.myparam1 }} {{ $.Values.mydict.myparam2 }}
Output:
original imported
Global parameters
Chart parameters are only accessible in that chart (and have limited availability in the dependent charts). One easy way to access the parameters of one chart in other linked charts is to use global parameters.
A global parameter has global scope — a parameter declared in a parent, child, or other linked chart becomes available in all linked charts at the same path:
# Chart.yaml:
name: myparent
dependencies:
- name: mychild1
- name: mychild2
# charts/mychild1/values.yaml:
global:
myparam: myvalue
# templates/example.yaml:
myparent: {{ $.Values.global.myparam }}
# charts/mychild1/templates/example.yaml:
mychild1: {{ $.Values.global.myparam }}
# charts/mychild2/templates/example.yaml:
mychild2: {{ $.Values.global.myparam }}
Output:
myparent: myvalue
---
mychild1: myvalue
---
mychild2: myvalue
Secret parameters (werf only)
You can use secret parameter files to store secret parameters. These files are encrypted and stored in the Git repository.
By default, werf tries to locate the .helm/secret-values.yaml file containing the encrypted parameters. When werf finds the file, it decrypts it and merges the decrypted parameters with the others:
# .helm/values.yaml:
plainParam: plainValue
# .helm/secret-values.yaml:
secretParam: 1000625c4f1d874f0ab853bf1db4e438ad6f054526e5dcf4fc8c10e551174904e6d0
{{ $.Values.plainParam }}
{{ $.Values.secretParam }}
Output:
plainValue
secretValue
Working with secret parameter files
The order in which the secret parameters files are processed:
-
Use an existing secret key or create a new one by running
werf helm secret generate-secret-key. -
Save the secret key to the
WERF_SECRET_KEYenvironment variable, or to<Git repository root>/.werf_secret_keyor<home directory>/.werf/global_secret_key. -
Use the
werf helm secret values edit .helm/secret-values.yamlcommand to open the secret parameters file and add the decrypted parameters to it or modify them. -
Save the file — it will be encrypted and saved in an encrypted form.
-
Commit the added/modified file
.helm/secret-values.yamlto Git. -
On subsequent werf invocations, the secret key must be present in the aforementioned environment variable or files, or werf will not be able to decrypt the secret parameter file.
Note that someone with access to the secret key can decrypt the contents of the secret settings file, so keep the secret key in a safe place!
When using the <Git repository root>/.werf_secret_key file, be sure to add it to .gitignore to avoid unintentionally saving it to the Git repository.
Many werf commands can also be run without a secret key (the --ignore-secret-key flag enables this), in which case the parameters will be available for use in an encrypted rather than decrypted form.
Additional secret parameter files
You can create and use extra secret files in addition to the .helm/secret-values.yaml file:
# .helm/secret-values-production.yaml:
secret: 1000625c4f1d874f0ab853bf1db4e438ad6f054526e5dcf4fc8c10e551174904e6d0
werf --secret-values .helm/secret-values-production.yaml
Rotating the secret key
To switch to a new secret key, decrypt each encrypted file with the old key and encrypt it with the new one. Cover every encrypted file:
- secret parameter files:
secret-values.yamlof the main chart and of every dependent chart, and the additional files passed with--secret-values; - secret files: every file in
secret/of the main chart and of every dependent chart.
Generate the new key first and store it where you keep secret keys, before changing any file: werf helm secret generate-secret-key. Then run the script below in the project directory with the old key in $OLD_SECRET_KEY and the new one in $NEW_SECRET_KEY, both exported (a key kept in a .werf_secret_key file has to be exported first, e.g. export OLD_SECRET_KEY="$(cat .werf_secret_key)"). It stops at the first error, re-encrypts every file before changing any of them, and copies the originals to a backup directory outside the project, listed in its index file:
#!/usr/bin/env bash
set -euo pipefail
umask 077
values_files=(.helm/secret-values.yaml) # every encrypted values file
files=(.helm/secret/tls.crt) # every file in secret/
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
rotate() {
WERF_SECRET_KEY="$OLD_SECRET_KEY" werf helm secret "$1" decrypt -o "$tmp/$3" "$2"
WERF_SECRET_KEY="$NEW_SECRET_KEY" werf helm secret "$1" encrypt -o "$tmp/$3.enc" "$tmp/$3"
}
n=0
for f in ${values_files[@]+"${values_files[@]}"}; do n=$((n + 1)); rotate values "$f" "$n"; done
for f in ${files[@]+"${files[@]}"}; do n=$((n + 1)); rotate file "$f" "$n"; done
backup="$(mktemp -d "${TMPDIR:-/tmp}/secret-rotation-backup.XXXXXX")"
n=0
for f in ${values_files[@]+"${values_files[@]}"} ${files[@]+"${files[@]}"}; do
n=$((n + 1)); cp -p "$f" "$backup/$n"; printf '%s\t%s\n' "$n" "$f" >>"$backup/index"
done
n=0
for f in ${values_files[@]+"${values_files[@]}"} ${files[@]+"${files[@]}"}; do n=$((n + 1)); cp "$tmp/$n.enc" "$f"; done
echo "All files re-encrypted with the new key. Originals are in $backup, remove it once you have checked the result."
If the script stops while copying, the files it already replaced are encrypted with the new key and the rest still with the old one; every original is in the backup directory.
A published chart keeps the publish-time --secret-values in .werf-data/secret-values.yaml, encrypted with the key used at publish. Re-encrypt this file in the unpacked chart in the same way, then pack the chart and upload it again, see Changing a published chart.
Compatibility of encrypted data between werf versions
Starting with werf v3.3.0 (Nelm v2.0.0-alpha.1), secrets are encrypted with AES-GCM, and each parameter in a secret parameter file keeps its YAML type: port: 8080 stays a number, enabled: true stays a boolean. Secrets encrypted by earlier versions are still read as before.
Earlier werf and Nelm versions can’t decrypt secrets encrypted by newer ones and fail, e.g. with a decode file ... error for a secret parameter file. Newer versions write secret parameter files and secret files in the new format with werf helm secret values edit and werf helm secret ... encrypt, including when rotating the secret key, and always use it for encrypted plans saved with werf plan --save-plan. Every werf and Nelm that reads such data, including CI jobs and werf bundle apply of bundles that contain it, must be upgraded as well.
Parameters encrypted by earlier versions don’t store their type, so they are always read as strings: port: 8080 becomes port: "8080", which may fail values.schema.json validation or change template logic. Re-encrypting them, e.g. when rotating the secret key, doesn’t help, because the type is already lost. The only way to restore the type is to re-enter the parameter: open the file with werf helm secret values edit and remove the quotes, e.g. change "8080" to 8080. Only the parameters you change are re-encrypted, the others keep their old encryption. When loading secret parameter files, werf warns about old-format parameters that look like numbers or booleans (werf render and werf bundle render show warnings only with --log-quiet=false or --log-debug).
Secret parameters in the release
werf saves the parameters from the --values, --secret-values and --set* options in the release, together with the parameters that export-values copies from them, and the parameters from --secret-values are saved in decrypted form. werf release get --print-values shows them, anyone who can read the release Secret in the cluster can read them, and changing only --secret-values creates a new release revision. Releases deployed with --secret-values by an earlier werf version get one new revision on the first deployment after the update. The parameters from secret-values.yaml of the charts are not saved among these parameters, but if Chart.yaml of the chart lists dependent charts in dependencies, the chart saved in the release contains them in decrypted form, and werf release get --print-values shows them too.
werf bundle publish stores the --secret-values files in .werf-data/secret-values.yaml of the published chart, encrypted. werf bundle apply decrypts them and saves them in the release in decrypted form among the parameters of the options, as werf converge does with --secret-values; werf release get --print-values shows them. Bundles published by werf 3.12 and earlier kept these files in secret-values.yaml of the chart, and werf bundle apply did not save their parameters in the release among the parameters of the options.
Information about the built images (werf only)
werf stores detailed information about the built images in $.Values.global.werf.images, available in all charts (main and dependent):
global:
werf:
images:
backend:
# Container registry address:
registry: example.org
# Repository namespace:
namespace: apps
# Image short name:
name: myapp
# Image tag:
tag: a243949601ddc3d4133c4d5269ba23ed58cb8b18bf2b64047f35abd2-1598024377816
# Image digest:
digest: sha256:ece15c4a8e7e04dd0afa25b85a51e3fba35eb31e0e1489a2f3e916da77e4e865
# Tag and digest combined:
tag_digest: "a243949...816@sha256:ece15c4a..."
# Full image name without tag (registry + repository):
image: example.org/apps/myapp
# Full repository path (namespace + name):
repository: apps/myapp
# Full image reference with digest:
ref: "example.org/apps/myapp:a243949...816@sha256:ece15c4a..."
# Full image reference with tag:
ref_tag: "example.org/apps/myapp:a243949...816"
# Repository path with tag and digest:
repository_ref: "apps/myapp:a243949...816@sha256:ece15c4a..."
# Repository path with tag:
repository_tag: "apps/myapp:a243949...816"
# Short name with tag and digest:
name_ref: "myapp:a243949...816@sha256:ece15c4a..."
# Short name with tag:
name_tag: "myapp:a243949...816"
This structured format allows you to use individual image components, which is useful when working with external charts that expect image values in a structured format:
image:
registry: {{ $.Values.global.werf.images.backend.registry }}
repository: {{ $.Values.global.werf.images.backend.repository }}
tag: {{ $.Values.global.werf.images.backend.tag }}
Since $.Values.global.werf has global scope, images is available in all dependent charts. You can also use export-values to map individual image fields to the format expected by an external chart:
# .helm/Chart.yaml:
dependencies:
- name: postgres-operator
export-values:
- parent: global.werf.images.pg.registry
child: image.registry
- parent: global.werf.images.pg.repository
child: image.repository
- parent: global.werf.images.pg.tag
child: image.tag
The postgres-operator chart will receive:
image:
registry: example.org
repository: apps/pg
tag: a243949601ddc3d4133c4d5269ba23ed58cb8b18bf2b64047f35abd2-1598024377816
export-values with global.* works the same way in Chart.yaml of a dependent chart: global there contains the global parameters of the main chart merged over those of the charts in between, the same as in the templates of the dependent chart, so global.werf.images can also be exported to the dependencies of a dependent chart.
Release information
werf stores release information in the properties of the $.Release object:
# Is the release being installed for the first time?
IsInstall: true
# Is the existing release being updated?
IsUpgrade: false
# Release name:
Name: myapp-production
# Kubernetes Namespace name:
Namespace: myapp-production
# Release revision:
Revision: 1
… and in $.Values.global.werf, available in all charts (werf only):
global:
werf:
# Name of the werf project:
name: myapp
# Environment:
env: production
# Kubernetes Namespace:
namespace: myapp-production
For backward compatibility, the same values are also available in $.Values.werf.
Example of use:
{{ $.Release.Namespace }}
{{ $.Values.global.werf.env }}
Output:
myapp-production
production
Chart information
werf stores information about the current chart in the $.Chart object:
# Is the chart the main one?
IsRoot: true
# Contents of the Chart.yaml:
Name: mychart
Version: 1.0.0
Type: library
KubeVersion: "~1.20.3"
AppVersion: "1.0"
Deprecated: false
Icon: https://example.org/mychart-icon.svg
Description: This is My Chart
Home: https://example.org
Sources:
- https://github.com/my/chart
Keywords:
- apps
Annotations:
anyAdditionalInfo: here
Dependencies:
- Name: redis
Condition: redis.enabled
Example of use:
{{ $.Chart.Name }}
Output:
mychart
Template information
werf stores information about the current template in the properties of the $.Template object:
# The relative path to the chart's templates directory:
BasePath: mychart/templates
# The relative path to the current template file:
Name: mychart/templates/example.yaml
Example of use:
{{ $.Template.Name }}
Output:
mychart/templates/example.yaml
Git commit information (werf only)
werf stores information about the Git commit that triggered its run in $.Values.global.werf.commit, available in all charts:
global:
werf:
commit:
date:
# The date of the Git commit that triggered werf (the human-readable form):
human: 2022-01-21 18:51:39 +0300 +0300
# The date of the Git commit that triggered werf (Unix time):
unix: 1642780299
# The hash of the Git commit that triggered werf:
hash: 1b28e6843a963c5bdb3579f6fc93317cc028051c
For backward compatibility, the same values are also available in $.Values.werf.commit.
Example of use:
{{ $.Values.global.werf.commit.hash }}
Output:
1b28e6843a963c5bdb3579f6fc93317cc028051c
Information about the Kubernetes cluster
werf provides information about the capabilities of the target Kubernetes cluster via the properties of the $.Capabilities object:
KubeVersion:
# The full version of the Kubernetes cluster:
Version: v1.20.0
# The major version of the Kubernetes cluster:
Major: "1"
# The minor version of the Kubernetes cluster:
Minor: "20"
# A list of APIs supported by the Kubernetes cluster:
APIVersions:
- apps/v1
- batch/v1
- # ...
… as well as methods of the $.Capabilities object:
APIVersions.Has <arg>— tells whether the Kubernetes cluster supports the API (e.g.,apps/v1) or resource (e.g.,apps/v1/Deployment) specified by the argument.
Example of use:
{{ $.Capabilities.KubeVersion.Version }}
{{ $.Capabilities.APIVersions.Has "apps/v1" }}
Output:
v1.20.0
true