Helm Configuration
Internal
Overview
chart installation or upgrade process consists in using the chart artifacts, which may optionally contain a hierarchy of dependencies, and applying specific configuration with the end goal of producing a release. This section describes where the default chart's configuration lives, how external configuration values can be provided to the installation process, how configuration is processed during installation and how the effective configuration values surface in the release.
Playground
Runtime Configuration Tree
A useful mental image we will often refer to in this section is that the helm installation runtime builds a unique runtime configuration tree that serves as authoritative source of truth for the release configuration. Various templates use it to pull effective configuration values to be rendered in the manifests. The initial structure of the tree is based on the content of the chart's values.yaml configuration file.
The content of the runtime configuration tree is displayed at installation time in the "COMPUTED VALUES" section, if the --debug flag is used with helm install. For the following values.yaml content:
# "a" configuration file values.yaml
color: 'blue'
details:
shape: 'square'
components:
- wheel
- trunk
"helm install --debug ..." produces the following output:
...
COMPUTED VALUES:
color: blue
details:
components:
- wheel
- trunk
shape: square
which corresponds to the following runtime configuration tree:
.
|
+- color: blue
|
+- details
|
+- shape: square
+- components: [wheel, trunk]
Runtime Configuration Tree in Presence of Dependencies
If a chart has one or more dependencies, each dependency (subchart) contributes a subtree to the runtime configuration tree. Each dependency subtree is installed in the root of the runtime configuration tree under a label equal with the subchart name. Assuming that the above configuration belongs to a chart "a", which has a dependency "b", which in turn has a values.yaml with the following content:
# "b" configuration file values.yaml
color: 'red'
then the effective runtime configuration tree at installation is:
.
|
+- color: blue
|
+- details
| |
| +- shape: square
| +- components: [wheel, trunk]
+-b
|
+-color: red
+-global: {}
If the second dependency, "c" is added to chart "a", and its values.yaml contains:
# "c" configuration file values.yaml
color: 'green'
the effective runtime configuration tree at installation is:
.
|
+- color: blue
|
+- details
| |
| +- shape: square
| +- components: [wheel, trunk]
+-b
| |
| +-color: red
| +-global: {}
|
+-c
|
+-color: green
+-global: {}
In case of nested dependencies, the runtime configuration subtrees corresponding to the nested dependencies are also nested. If, for example, the chart "a" depends on "b" and "b" depends on "c", while the rest of the configuration presented above stays the same, the runtime configuration tree built during the installation of chart "a" will looks similar to:
.
|
+- color: blue
|
+- details
| |
| +- shape: square
| +- components: [wheel, trunk]
+-b
|
+-color: red
+-global: {}
|
+-c
|
+-color: green
+-global: {}
While being installed, during template rendering phase, the dependencies pull their values from their corresponding subtrees, not from the main configuration tree. With the configuration examples presented above, if "b" wants to get its color while being deployed as a dependency of "a", it should use {{ .Values.color }} and not {{ .Values.b.color }}, which does not make any sense if the dependency is used on its own, in a standalone context. If {{ .Values.b.color }} is used, even when "b" is declared to be a dependency of "a", rendering fails with:
Error: render error in "a/charts/b/templates/pod.yaml": template: a/charts/b/templates/pod.yaml:6:22: executing "a/charts/b/templates/pod.yaml" at <.Values.b.color>: nil pointer evaluating interface {}.color
For more details about the Values object, see Rendering Configuration in Templates below.
Default Configuration
A chart comes with default configuration specified in the values.yaml file. The content of this file is used to build the initial instance of the runtime configuration tree. The content of the values.yaml file can rendered, verbatim, with:
helm inspect values <chart>
Unless overridden as described blow, these values can be accessed by templates via the Values object. For subcharts, the values configured in their values.yaml files are accessible as described in the Runtime Configuration Tree in Presence of Dependencies section above.
Overriding Default Configuration
The default values.yaml values can be overridden by values coming from sources listed below. If two or more of configuration sources listed above are used at the same time, the lowest in the list has priority:
- If this is a subchart, by the corresponding values present in the values.yaml file of the parent chart - see Parent Chart Overrides below.
- Values supplied in a file, passed to the install or upgrade command with the -f|--values flag - see Values Supplied in Files below.
- Values passed with --set or --set-string to helm install or upgrade - see --set Command Line Arguments below.
- The content of a file passed with --set-file on helm install or upgrade
Parent Chart Overrides
With the Runtime Configuration Tree in Presence of Dependencies examples above, where "b" is a dependency and "a" is the parent (dependent) chart, we can override the default "color" configured in "b"'s values.yaml ("red") by specifying the following override in the values.yaml file of the parent chart "a". The override configuration should be present in a configuration subtree rooted in the name of subchart.
# "a" configuration file values.yaml
color: 'blue'
# in this context, "b" should be the chart name of the dependency chart (subchart)
b:
color: 'fuchsia'
New configuration, not only already existing default values, can be specified this way, as well.
Values Supplied in Files
Configuration overrides may be specified in YAML-formatted files introduced with the -f|--values install|upgrade command line parameter.
helm install -f|--values ./test.yaml ...
In case we need to override dependent chart configuration, specify the override in a dependency chart name-rooted configuration sub-tree. In the example below, "b" is the name of the subchart:
...
b:
color: 'brown'
Note that "b.color" is NOT equivalent with the syntax shown above and must not be used.
There is another command line argument that implies using configuration files: --set-file. However, the files expected by --set-file have a different format. More details are available on the helm install page.
Environment Variables in Files
Various materials seem to suggest that environment variables referred in configuration file pulled with -f|--values are resolved but I have not been able to make that work.
--set Command Line Arguments
Individual configuration options can be specified with --set or --set-string.
- ‘(.) --set for dependent charts. We need to provide the name of dependent chart up top. Understand why we need c3-selenium.selenium….
and --set-file. If both --set and --values are used, the --set-specified configuration values are merged into the configuration values specified with --values, with higher precedence. Overrides specified with --set are persisted in a ConfigMap and can be viewed for a given release with helm get value <release-name>:
helm install --set size=10 ...
A value specified values.yaml can be effectively effectively eliminated, by setting that value to null with
... --set <key>=null ...
For more details on relative precedence of different sources of configuration data, see:
Overriding Array Elements
If the value file contains array structures, individual elements of the arrays can be identified from command line and overridden using the [...] syntax. If values.yaml contains:
colors: - name: 'blue' shade: 'dark' - nane: 'red' shade: 'light'
the "name" of the first element of the array can be overridden with:
--set colors[0].name=green,colors[0].shade=faded
The above is equivalent with:
--set colors[0].name=green \ --set colors[0].shade=faded
Warning 1 If an array element contains more than on key/value mapping, replacing just one key/value mapping with --set will discard the other ones, so you will need to set all key/value pairs at the same time. For the above example, --set colors[0].name to green will yield an empty shade for element 0. This behavior was noticed with Helm 2.14.3.
Warning 2 Setting just one array element will discard all others, so all elements must be replaced. This behavior was noticed with Helm 2.14.3.
TODO: https://helm.sh/docs/using_helm/#the-format-and-limitations-of-set
Removing Configuration Values
A value specified values.yaml can be effectively effectively eliminated, by setting that value to null with
... --set <key>=null
Viewing User-Supplied Values
helm install --debug ...
USER-SUPPLIED VALUES:
...
Rendering Configuration in Templates
The 'Values' Object
Reconcile this and Helm_Templates#Values.
The 'Values' Object offers access to the runtime configuration tree, containing the effective configuration values which result after overriding default value with installation-time values.
The effective value specified by one or more of these sources can be accessed from templates with:
{{ .Values.fieldName }}
Exporting Subchart Configuration Elements
requirements.yaml import-values
TODO: https://helm.sh/docs/developing_charts/#using-the-child-parent-format, https://github.com/ovidiuf/playground/blob/master/helm/export/README.md