Helm Configuration

Internal

• Helm Concepts

Overview

The 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 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

https://github.com/ovidiuf/playground/tree/master/helm/configuration

Runtime Configuration Tree

A useful mental model 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 the helm install command. 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 plugged into 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 show values <chart>

Unless overridden as described below, 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.

Querying Values after Installation

helm get values --all <release-name>

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 the helm install or helm upgrade - see --set Command Line Arguments below.
• The content of a file passed with --set-file to the helm install or helm upgrade commands - see --set Command Line Arguments below.

The values for all configuration parameters that were overridden during installation can be pulled with:

helm get values <release-name>

Internally, configuration override values for each version of a release is maintained in a per-release per-version ConfigMap , in the "kube-system" namespace

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 command line parameter for the helm install or helm upgrade command:

helm install -f|--values ./test.yaml ...

In case we need to override dependent chart configuration, specify the override in a configuration sub-tree rooted in the dependency chart name. 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 infers the type of the argument, in the same way YAML does. For example, --set size=10 places an integer in the runtime configuration tree. --set-string forces conversion to string values that otherwise would have have had their type inferred.

helm install --set color=gray ...

--set can be specified multiple times. If specified multiple time for the same value, the priority will be given to the last (right-most) set specified.

The --set argument is a key=value key/value pair, where the key is usually a value.yaml key.

In case of hierarchical configuration elements, their name can be unwound for --set:

components:
  engine:
    capacity: 4

helm install --set components.engine.capacity=5 ...

To override subchart configuration, prefix the configuration element name with the name of the subchart. In the following example, "b" is the name of the dependency chart:

helm install --set b.color=alabaster ...

Multiple values are separated by ",":

helm install --set a=b,c=d

For more --set format options see:

The Format and Limitations of --set

Mixing --set and --values

TODO

Overriding Array Elements

If the value file contains array structures, the entire value of the array can be overridden with (avoid spaces after commas, apparently helm does not trim those and the final array element values will include those):

helm install --set shapes="{circle,square,rectangle}" ...

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.

Eliminating Configuration Elements

Any value that is specified in values.yaml can be effectively effectively eliminated, by setting that value to null using all of the above methods (parent chart overrides, values supplied in files and --set command line arguments). For example, --set can be used as follows:

helm install --set <key>=null ...

Viewing User-Supplied Values

helm install --debug ...

USER-SUPPLIED VALUES:
...

helm get values <release-name>

Rendering Configuration in Templates

The content of the runtime configuration tree is made available to the template rendering engine via the Values built-in object. The effective value of any configuration element can be accessed from a template by prefixing the configuration element name with .Values.:

 {{ .Values.<fieldName> }}

Field names that contain dashes, while supported, are not rendered in a straightforward manner. For more details, see:

values.yaml | Field Names and Dashes

For more details on accessing configuration from templates see:

Helm Templates .Values Built-in Object

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

What if the configuration is overridden in subchart?