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
Reusing the example presented in the Runtime Configuration Tree in Presence of Dependencies section 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:
# "a" configuration file values.yaml
color: 'blue'
# in this context, "b" should be the chart name of the dependency chart
b:
color: 'fuchsia'
Values Supplied in Files
Difference between -f|--values and --set-file
--set Command Line Arguments
TODO
Charts may, and usually will, expose configuration options. To see what configuration options are available for a chart use helm inspect values. Any available configuration option can be overridden by providing a YAML-formatted file during installation with the helm install -f|--values flag, or individually, on a configuration option basis, with --set.
The effective value specified by one or more of these sources can be accessed from templates with:
{{ .Values.fieldName }}
A value specified values.yaml can be effectively effectively eliminated, by setting that value to null with
... --set <key>=null
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.
Overriding Default Configuration TO DEPLETE
Overriding configuration can be provided:
- on command line: Helm_install#Overriding_Default_Configuration
- in files: Helm_install#Overriding_Default_Configuration
- in environment variables
The actual configuration hierarchy can be rendered during the release with --debug.
Each piece of configuration can be referred to from templates with .Values
Effective Values
All user-supplied values and computed values can be inspected at installation time if the --debug flag is provided to helm install:
helm install --debug ...
USER-SUPPLIED VALUES:
{}
COMPUTED VALUES:
color: blue
subject: have a nice day
Exporting 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
TODO
TODO
- ‘(.) --set for dependent charts. We need to provide the name of dependent chart up top. Understand why we need c3-selenium.selenium….