Helm Chart values.yaml: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(35 intermediate revisions by the same user not shown)
Line 1: Line 1:
=External=
* https://helm.sh/docs/topics/charts/#values-files
=Internal=
=Internal=


* [[Helm_Concepts#Chart_Configuration|Chart Configuration]]
* [[Helm_Concepts#Chart_Configuration|Values and Chart Configuration]]
* [[Helm_Concepts#values.yaml|Chart Layout]]
* [[Helm_Concepts#values.yaml|Chart Layout]]
* [[Helm_Concepts#Templates|Templates]]
* [[Helm_Concepts#Templates|Templates]]
* [[Helm_inspect#Configuration_Options|helm inspect values]]
* [[Helm_show#Configuration_Options|helm show values]]


=Overview=
=Overview=


The default configuration values for a chart. The file is mandatory. The content of this file is displayed by [[Helm_inspect#Configuration_Options|helm inspect values]].
A file that contains the default configuration values for a chart. The file is mandatory. The content of this file can be displayed with the <code>[[Helm_show#Configuration_Options|helm show values]]</code> command. The values specified in this file can be accessed in templates as part of the [[Helm_Templates#Values|<tt>Values</tt> template object]]. Note that the effective value applied to a template is the result of overlaying this <code>value.yaml</code> file with values coming from other [[Helm_Configuration#Runtime_Configuration_Tree|sources]].
 
When creating a new <code>value.yaml</code>, it is fine to use the root namespace for application-specific keys. Many well-known, production-deployed O/S charts do so.
 
=Syntax=
<code>value.yaml</code> contains YAML-structured configuration data, where YAML path are referred to as field names.
 
=Field Names and Dashes=
 
⚠️ Field names, or in case of structured configuration, constituent elements of field names, may not contain dashes, even if YAML format allows that.
 
A field name that contains dashes may not be read from a template in a straightforward way. For example, configuration expressed as:
 
<syntaxhighlight lang='yaml'>
district:
  sub-division: north
</syntaxhighlight>
 
may not be rendered in a straightforward way in a template, as:
 
<syntaxhighlight lang='yaml'>
data:
  value: {{ .Values.district.sub-division }}
</syntaxhighlight>
 
fails when rendered:
<syntaxhighlight lang='text'>
Error: parse error at (simplest/templates/configmap.yaml:6): bad character U+002D '-'
</syntaxhighlight>
 
There is an inelegant workaround, though:
<syntaxhighlight lang='yaml'>
data:
  value: {{ index .Values "district" "sub-division" }}
</syntaxhighlight>


=Values Best Practices=
=<span id='Values_Best_Practices'></span><tt>values.yaml</tt> Best Practices=


{{External|https://helm.sh/docs/chart_best_practices/#values}}
{{External|https://helm.sh/docs/chart_best_practices/values/}}


Variable name should begin with a lowercase letter, and words should be separated with camelcase. All of Helm’s built-in variables begin with an uppercase letter to easily distinguish them from user-defined values.  
Variable name should begin with a lowercase letter, and words should be separated with camelcase. All of Helm’s built-in variables begin with an uppercase letter to easily distinguish them from user-defined values.  


All string values should be quoted, everything else should use implicit type conversion. Also see [[YAML#Data_Types|YAML Data Types]].
All string values should be quoted, everything else should use implicit type conversion. Also see [[YAML#Data_Types|YAML Data Types]].
Values specified in this file can be potentially overridden by values specified with <code>[[Helm_install#--set|--set]]</code>, so it is a good idea to come up with variable names that can be easily overridden this way. For example:
<font size=-1>
servers:
  first:
    port: 80
</font>
if preferable to:
<font size=-1>
servers:
- name: first
    port: 80
</font>
because in the first case the override is:
<font size=-1>
--set servers.first.port=81
</font>
while in the second case is:
<font size=-1>
--set servers[0].port=81
</font>
which is sensitive to the potential change in order.
Every defined property should be documented. The documentation string should begin with the name of the property that it describes, and then give at least one sentence description. Beginning each comment with the name of the parameter it documents makes it easy to grep out documentation, and will enable documentation tools to reliably correlate doc strings with the parameters they describe:
<font size=-1>
# serverHost is the host name for the webserver
serverHost:  "example"
</font>


=Example=
=Example=
 
<font size=-1>
  imageRegistry: "quai.io/something"
  imageRegistry: "quai.io/something"
  dockerTag: "latest"
  dockerTag: "latest"
  pullPolicy: "always"
  pullPolicy: "always"
  storage: "s3"
  storage: "s3"
</font>


=TODO=
=Organizatorium=
 
<font color=darkkhaki>
TO PROCESS:
* https://helm.sh/docs/developing_charts/#quote-strings-don-t-quote-integers
* https://helm.sh/docs/developing_charts/#quote-strings-don-t-quote-integers
</font>

Latest revision as of 01:12, 6 February 2022

External

Internal

Overview

A file that contains the default configuration values for a chart. The file is mandatory. The content of this file can be displayed with the helm show values command. The values specified in this file can be accessed in templates as part of the Values template object. Note that the effective value applied to a template is the result of overlaying this value.yaml file with values coming from other sources.

When creating a new value.yaml, it is fine to use the root namespace for application-specific keys. Many well-known, production-deployed O/S charts do so.

Syntax

value.yaml contains YAML-structured configuration data, where YAML path are referred to as field names.

Field Names and Dashes

⚠️ Field names, or in case of structured configuration, constituent elements of field names, may not contain dashes, even if YAML format allows that.

A field name that contains dashes may not be read from a template in a straightforward way. For example, configuration expressed as:

district:
  sub-division: north

may not be rendered in a straightforward way in a template, as:

data:
  value: {{ .Values.district.sub-division }}

fails when rendered:

Error: parse error at (simplest/templates/configmap.yaml:6): bad character U+002D '-'

There is an inelegant workaround, though:

data:
  value: {{ index .Values "district" "sub-division" }}

values.yaml Best Practices

https://helm.sh/docs/chart_best_practices/values/

Variable name should begin with a lowercase letter, and words should be separated with camelcase. All of Helm’s built-in variables begin with an uppercase letter to easily distinguish them from user-defined values.

All string values should be quoted, everything else should use implicit type conversion. Also see YAML Data Types.

Values specified in this file can be potentially overridden by values specified with --set, so it is a good idea to come up with variable names that can be easily overridden this way. For example:

servers:
  first:
   port: 80

if preferable to:

servers:
- name: first
   port: 80

because in the first case the override is:

--set servers.first.port=81

while in the second case is:

--set servers[0].port=81

which is sensitive to the potential change in order.

Every defined property should be documented. The documentation string should begin with the name of the property that it describes, and then give at least one sentence description. Beginning each comment with the name of the parameter it documents makes it easy to grep out documentation, and will enable documentation tools to reliably correlate doc strings with the parameters they describe:

# serverHost is the host name for the webserver
serverHost:  "example"

Example

imageRegistry: "quai.io/something"
dockerTag: "latest"
pullPolicy: "always"
storage: "s3"

Organizatorium

TO PROCESS: