Helm Configuration: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(91 intermediate revisions by the same user not shown)
Line 5: Line 5:
=Overview=
=Overview=


[[#Chart|chart]] installation or upgrade process consists in using the chart artifacts, which may optionally contain a hierarchy of [[Helm_Dependencies|dependencies]], and applying specific configuration with the end goal of producing a [[#Release|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.
The [[#Chart|Chart]] installation or upgrade process consists in using the chart artifacts, which may optionally contain a hierarchy of [[Helm_Dependencies|dependencies]], and applying specific configuration with the end goal of producing a [[#Release|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=
=Playground=
{{External|https://github.com/ovidiuf/playground/tree/master/helm/configuration}}
{{External|https://github.com/ovidiuf/playground/tree/master/helm/configuration}}
Line 11: Line 12:
=Runtime Configuration Tree=
=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 [[Helm Chart values.yaml|values.yaml]] configuration file.
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 <code>[[Helm_Chart_values.yaml#Overview|values.yaml]]</code> 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#Debug|helm install]]. For the following values.yaml content:
The content of the runtime configuration tree is displayed at installation time in the "COMPUTED VALUES" section, if the <code>--debug</code> flag is used with the <code>[[Helm_install#Debug|helm install]]</code> command. For the following <code>values.yaml</code> content:
<syntaxhighlight lang='yaml'>
<syntaxhighlight lang='yaml'>
# "a" configuration file values.yaml
# "a" configuration file values.yaml
Line 24: Line 25:
</syntaxhighlight>
</syntaxhighlight>


"helm install --debug ..." produces the following output:
<code>helm install --debug ...</code> produces the following output:
<syntaxhighlight lang='text'>
<syntaxhighlight lang='text'>
...
...
Line 36: Line 37:
</syntaxhighlight>  
</syntaxhighlight>  
which corresponds to the following runtime configuration tree:
which corresponds to the following runtime configuration tree:
<syntaxhighlight lang='text'>
<font size=-1>
  .
  .
  |
  ├─ color: blue
+- color: blue
  └─ details
  |
    ├─ shape: square
+- details
    └─ components: [wheel, trunk]
      |
</font>  
      +- shape: square
      +- components: [wheel, trunk]
</syntaxhighlight>  


==Runtime Configuration Tree in Presence of Dependencies==
==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:
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 <code>values.yaml</code> with the following content:
<syntaxhighlight lang='yaml'>
<syntaxhighlight lang='yaml'>
# "b" configuration file values.yaml
# "b" configuration file values.yaml
Line 54: Line 52:
</syntaxhighlight>
</syntaxhighlight>
then the effective runtime configuration tree at installation is:
then the effective runtime configuration tree at installation is:
<syntaxhighlight lang='text'>
<font size=-1>
  .
  .
  |
  ├─ color: blue
+- color: blue
  ├─ details
  |
  │  ├─ shape: square
+- details
  │  └─ components: [wheel, trunk]  
  |    |
  └─ b
|    +- shape: square
    ├─ color: red
  |    +- components: [wheel, trunk]
    └─ global: {}
  +-b
</font>
  |
If the second dependency, "c" is added to chart "a", and its <code>values.yaml</code> contains:
  +-color: red
  +-global: {}
</syntaxhighlight>
If the second dependency, "c" is added to chart "a", and its values.yaml contains:
<syntaxhighlight lang='yaml'>
<syntaxhighlight lang='yaml'>
# "c" configuration file values.yaml
# "c" configuration file values.yaml
Line 74: Line 68:
</syntaxhighlight>
</syntaxhighlight>
the effective runtime configuration tree at installation is:
the effective runtime configuration tree at installation is:
<syntaxhighlight lang='text'>
<font size=-1>
  .
  .
  |
  ├─ color: blue
+- color: blue
  ├─ details
  |
  │  ├─ shape: square
+- details
  │  └─ components: [wheel, trunk]  
  |    |
  ├─ b
|    +- shape: square
  ├─ color: red
  |    +- components: [wheel, trunk]
  │  └─ global: {}
  +-b
  └─ c
  | |
    ├─ color: green
  | +-color: red
    └─ global: {}
  | +-global: {}
</font>
  |
+-c
  |
  +-color: green
  +-global: {}
</syntaxhighlight>


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:
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:
<syntaxhighlight lang='text'>
<font size=-1>
  .
  .
  |
  ├─ color: blue
+- color: blue
  ├─ details
  |
  │  ├─ shape: square
+- details
  │  └─ components: [wheel, trunk]  
  |    |
  └─ b
|    +- shape: square
    ├─ color: red
  |    +- components: [wheel, trunk]
    ├─ global: {}
  +-b
    └─ c
  |
      ├─ color: green
  +-color: red
      └─ global: {}
  +-global: {}
</font>
  |
  +-c
    |
    +-color: green
    +-global: {}
</syntaxhighlight>


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 <code>&#123;{ .Values.color }}</code> and not <code>&#123;{ .Values.b.color }}</code>, which does not make any sense if the dependency is used on its own, in a standalone context. If <code>&#123;{ .Values.b.color }}</code> is used, even when "b" is declared to be a dependency of "a", rendering fails with:
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 <code>&#123;{ .Values.color }}</code> and not <code>&#123;{ .Values.b.color }}</code>, which does not make any sense if the dependency is used on its own, in a standalone context. If <code>&#123;{ .Values.b.color }}</code> is used, even when "b" is declared to be a dependency of "a", rendering fails with:
Line 123: Line 105:
=Default Configuration=
=Default Configuration=


A chart comes with default configuration specified in the [[Helm Chart values.yaml|values.yaml]] file. The content of this file is used to build the initial instance of the [[#Runtime_Configuration_Tree|runtime configuration tree]]. The content of the values.yaml file can rendered, verbatim, with:
A chart comes with default configuration specified in the <code>[[Helm Chart values.yaml#Overview|values.yaml]]</code> file. The content of this file is used to build the initial instance of the [[#Runtime_Configuration_Tree|runtime configuration tree]]. The content of the <code>values.yaml</code> file can rendered, verbatim, with:
  helm [[Helm_inspect#Content_of_values.yaml|inspect values]] <''chart''>
<font size=-1>
  helm [[Helm_show#Content_of_values.yaml|show values]] <''chart''>
</font>
Unless [[Helm_Concepts#Overriding_Default_Configuration|overridden]] as described below, these values can be accessed by templates via the [[#The_.27Values.27_Object|Values]] object. For [[Helm_Dependencies#Subcharts|subcharts]], the values configured in their <code>values.yaml</code> files are accessible as described in the [[#Runtime_Configuration_Tree_in_Presence_of_Dependencies|Runtime Configuration Tree in Presence of Dependencies]] section above.


Unless [[Helm_Concepts#Overriding_Default_Configuration|overridden]] as described blow, these values can be accessed by templates via the [[#The_.27Values.27_Object|Values]] object. For [[Helm_Dependencies#Subcharts|subcharts]], the values configured in their [[Helm Chart values.yaml|values.yaml]] files are accessible as described in the [[#Runtime_Configuration_Tree_in_Presence_of_Dependencies|Runtime Configuration Tree in Presence of Dependencies]] section above.
=Querying Values after Installation=
{{Internal|Helm_get#Get_Values|<tt>helm get values --all <release-name></tt>}}


=<span id='Values_and_Chart_Configuration'></span>Overriding Default Configuration=
=<span id='Values_and_Chart_Configuration'></span>Overriding Default Configuration=


The default  [[Helm Chart values.yaml|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:
The default  <code>[[Helm Chart values.yaml|values.yaml]]</code> 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 [[Helm_Dependencies#Subcharts|subchart]], by the corresponding values present in the [[Helm Chart values.yaml|values.yaml]] file of the parent chart - see [[#Parent_Chart_Overrides|Parent Chart Overrides]] below.
* If this is a [[Helm_Dependencies#Subcharts|subchart]], by the corresponding values present in the <code>values.yaml</code> file of the parent chart - see [[#Parent_Chart_Overrides|Parent Chart Overrides]] below.
* Values supplied in a file, passed to the install or upgrade command with the [[Helm_install#Overriding_Default_Configuration|-f|--values]] flag - see [[#Values_Supplied_in_Files|Values Supplied in Files]] below.
* Values supplied in a file, passed to the install or upgrade command with the <code>[[Helm_install#-f.7C--values|-f|--values]]</code> flag - see [[#Values_Supplied_in_Files|Values Supplied in Files]] below.
* Values passed with [[Helm_install#--set|--set]] or [[Helm_install#--set|--set-string]] to helm install or upgrade - see [[#--set_Command_Line_Arguments|--set Command Line Arguments]] below.
* Values passed with <code>[[Helm_install#--set|--set]]</code> or <code>[[Helm_install#--set|--set-string]]</code> to the <code>helm install</code> or <code>helm upgrade</code> - see [[#--set_Command_Line_Arguments|--set Command Line Arguments]] below.
* <font color=darkgray>The content of a file passed with --set-file on helm install or upgrade</font>
* The content of a file passed with <code>--set-file</code> to the <code>helm install</code> or <code>helm upgrade</code> commands - see [[#--set_Command_Line_Arguments|--set Command Line Arguments]] below.
 
The values for all configuration parameters that were overridden during installation can be pulled with:
<font size=-1>
helm [[Helm_get#Get_Values|get values]] <''release-name''>
</font>
Internally, configuration override values for each version of a release is maintained in a per-release per-version [[Kubernetes_Cluster_Configuration_Concepts#ConfigMap|ConfigMap]] , in the "kube-system" namespace


==Parent Chart Overrides==
==Parent Chart Overrides==


Reusing the example presented in the [[Helm_Configuration#Runtime_Configuration_Tree_in_Presence_of_Dependencies|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:
With the [[Helm_Configuration#Runtime_Configuration_Tree_in_Presence_of_Dependencies|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 <code>values.yaml</code> ("red") by specifying the following override in the <code>values.yaml</code> file of the parent chart "a". The override configuration should be present in a configuration subtree rooted in the name of subchart.
<syntaxhighlight lang='yaml'>
<syntaxhighlight lang='yaml'>
# "a" configuration file values.yaml
# "a" configuration file values.yaml
color: 'blue'
color: 'blue'
# in this context, "b" should be the chart name of the dependency chart
# in this context, "b" should be the chart name of the dependency chart (subchart)
b:
b:
   color: 'fuchsia'
   color: 'fuchsia'
</syntaxhighlight>
</syntaxhighlight>
New configuration, not only already existing default values, can be specified this way, as well.


==Values Supplied in Files==
==Values Supplied in Files==


<font color=darkgray>Difference between -f|--values and --set-file</font>
Configuration overrides may be specified in YAML-formatted files introduced with the <code>[[Helm_install#-f.7C--values|-f|--values]]</code> command line parameter for the <code>helm install</code> or <code>helm upgrade</code> command:
 
<font size=-1>
helm install [[Helm_install#-f.7C--values|-f|--values]] ./test.yaml ...
</font>
 
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:
 
<syntaxhighlight lang='yaml'>
...
b:
  color: 'brown'
</syntaxhighlight>
 
Note that "b.color" is NOT equivalent with the syntax shown above and must not be used.


[[Helm_install#Overriding_Default_Configuration]]
There is another command line argument that implies using configuration files: <code>[[Helm_install#--set-file|--set-file]]</code>. However, the files expected by <code>--set-file</code> have a different format. More details are available on the <code>[[Helm_install#--set-file|helm install]]</code> page.


===Environment Variables in Files===
===Environment Variables in Files===
Various materials seem to suggest that environment variables referred in configuration file pulled with <code>-f|--values</code> are resolved but I have not been able to make that work.


==--set Command Line Arguments==
==<tt>--set</tt> Command Line Arguments==


[[Helm_install#Overriding_Default_Configuration]]
Individual configuration options can be specified with <code>[[Helm_install#--set.2C_--set--string|--set]]</code> or <code>[[Helm_install#--set.2C_--set--string|--set-string]]</code>. <code>--set</code> infers the type of the argument, in the same way [[YAML#Scalars|YAML does]]. For example, <code>--set size=10</code> places an integer in the runtime configuration tree. <code>--set-string</code> forces conversion to string values that otherwise would have have had their type inferred.


===Removing Configuration Values===
<syntaxhighlight lang='bash'>
helm install --set color=gray ...
</syntaxhighlight>


A value specified [[Helm Chart values.yaml|values.yaml]] can be effectively effectively eliminated, by setting that value to <tt>null</tt> with
<code>--set</code> 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.


... --set <''key''>=null
The <code>--set</code> argument is a <tt>''key''=''value''</tt> key/value pair, where the key is usually a <code>value.yaml</code> key.


=Rendering Configuration in Templates=
In case of hierarchical configuration elements, their name can be unwound for <code>--set</code>:
<syntaxhighlight lang='yaml'>
components:
  engine:
    capacity: 4
</syntaxhighlight>
<syntaxhighlight lang='bash'>
helm install --set components.engine.capacity=5 ...
</syntaxhighlight>


==The 'Values' Object==
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:


<font color=darkgray>Reconcile this and [[Helm_Templates#Values]].
<syntaxhighlight lang='bash'>
helm install --set b.color=alabaster ...
</syntaxhighlight>


The 'Values' Object offers access to the [[#Runtime_Configuration_Tree|runtime configuration tree]], containing the effective configuration values which result after overriding default value with installation-time values.
Multiple values are separated by ",":
<syntaxhighlight lang='bash'>
helm install --set a=b,c=d
</syntaxhighlight>
For more <code>--set</code> format options see: {{External|[https://helm.sh/docs/using_helm/#the-format-and-limitations-of-set The Format and Limitations of --set]}}


The effective value specified by one or more of these sources can be accessed from templates with:
==Mixing <tt>--set</tt> and <tt>--values</tt>==
<Font color=darkkhaki>TODO</font>


  &#123;{ [[Helm_Templates#Values|.Values.fieldName]] }}
==Overriding Array Elements==


[[Helm_Chart_values.yaml]]
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):
</font>


=Overriding Default Configuration TO DEPLETE=
<syntaxhighlight lang='bash'>
helm install --set shapes="{circle,square,rectangle}" ...
</syntaxhighlight>


Individual elements of the arrays can be identified from command line and overridden using the <code>[</code>...<code>]</code> syntax. If <code>values.yaml</code> contains:


==Effective Values==
<syntaxhighlight lang='yaml'>
colors:
- name: 'blue'
  shade: 'dark'
- nane: 'red'
  shade: 'light'
</syntaxhighlight>


All user-supplied values and computed values can be inspected at installation time if the --debug flag is provided to [[helm install#Debug|helm install]]:
the "name" of the first element of the array can be overridden with:


  helm install --debug ...
<syntaxhighlight lang='bash'>
  --set colors[0].name=green,colors[0].shade=faded
</syntaxhighlight>


USER-SUPPLIED VALUES:
The above is equivalent with:
{}
COMPUTED VALUES:
color: blue
subject: have a nice day


=Exporting Configuration Elements=
<syntaxhighlight lang='bash'>
--set colors[0].name=green \
--set colors[0].shade=faded
</syntaxhighlight>


===requirements.yaml import-values===
{{Warn|'''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.}}
TODO: https://helm.sh/docs/developing_charts/#using-the-child-parent-format, https://github.com/ovidiuf/playground/blob/master/helm/export/README.md


==TODO==
{{Warn|'''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====
==Eliminating Configuration Elements==


<font color=darkgray>
Any value that is specified in <code>[[Helm Chart values.yaml|values.yaml]]</code> can be effectively effectively eliminated, by setting that value to <code>null</code> using all of the above methods ([[#Parent_Chart_Overrides|parent chart overrides]], [[#Values_Supplied_in_Files|values supplied in files]] and [[#--set_Command_Line_Arguments|--set command line arguments]]). For example, <code>--set</code> can be used as follows:
* ‘(.) --set for dependent charts. We need to provide the name of dependent chart up top. Understand why we need c3-selenium.selenium….
<font size=-1>
helm install --set <''key''>=null ...
</font>


==Viewing User-Supplied Values==
<font size=-1>
helm install --debug ...
</font>
<syntaxhighlight lang='text'>
USER-SUPPLIED VALUES:
...
</syntaxhighlight>
<font size=-1>
helm [[Helm_get#Get_Values|get values]] <''release-name''>
</font>


=Rendering Configuration in Templates=


<span id='The_.27Values.27_Object'></span>The content of the [[#Runtime_Configuration_Tree|runtime configuration tree]] is made available to the template rendering engine via the <code>Values</code> built-in object. The effective value of any configuration element can be accessed from a template by prefixing the configuration element name with <code>.Values.</code>:
<font size=-1>
  &#123;{ .Values.<''fieldName''> }}
</font>
</font>
Field names that contain dashes, while supported, are not rendered in a straightforward manner. For more details, see:
{{Internal|Helm_Chart_values.yaml#Field_Names_and_Dashes|values.yaml &#124; Field Names and Dashes}}
For more details on accessing configuration from templates see: {{Internal|Helm_Templates#Values|Helm Templates .Values Built-in Object}}
=Exporting Subchart Configuration Elements=
==requirements.yaml import-values==
<font color='darkkhaki'>
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?
</font >

Latest revision as of 07:42, 9 February 2022

Internal

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:

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:

What if the configuration is overridden in subchart?