github.com/koderover/helm@v2.17.0+incompatible/docs/chart_best_practices/values.md (about)

     1  # Values
     2  
     3  This part of the best practices guide covers using values. In this part of the
     4  guide, we provide recommendations on how you should structure and use your
     5  values, with focus on designing a chart's `values.yaml` file.
     6  
     7  ## Naming Conventions
     8  
     9  Variables names should begin with a lowercase letter, and words should be
    10  separated with camelcase:
    11  
    12  Correct:
    13  
    14  ```yaml
    15  chicken: true
    16  chickenNoodleSoup: true
    17  ```
    18  
    19  Incorrect:
    20  
    21  ```yaml
    22  Chicken: true  # initial caps may conflict with built-ins
    23  chicken-noodle-soup: true # do not use hyphens in the name
    24  ```
    25  
    26  Note that all of Helm's built-in variables begin with an uppercase letter to
    27  easily distinguish them from user-defined values: `.Release.Name`,
    28  `.Capabilities.KubeVersion`.
    29  
    30  ## Flat or Nested Values
    31  
    32  YAML is a flexible format, and values may be nested deeply or flattened.
    33  
    34  Nested:
    35  
    36  ```yaml
    37  server:
    38    name: nginx
    39    port: 80
    40  ```
    41  
    42  Flat:
    43  
    44  ```yaml
    45  serverName: nginx
    46  serverPort: 80
    47  ```
    48  
    49  In most cases, flat should be favored over nested. The reason for this is that
    50  it is simpler for template developers and users.
    51  
    52  
    53  For optimal safety, a nested value must be checked at every level:
    54  
    55  ```
    56  {{ if .Values.server }}
    57    {{ default "none" .Values.server.name }}
    58  {{ end }}
    59  ```
    60  
    61  For every layer of nesting, an existence check must be done. But for flat
    62  configuration, such checks can be skipped, making the template easier to read
    63  and use.
    64  
    65  ```
    66  {{ default "none" .Values.serverName }}
    67  ```
    68  
    69  When there are a large number of related variables, and at least one of them
    70  is non-optional, nested values may be used to improve readability.
    71  
    72  ## Make Types Clear
    73  
    74  YAML's type coercion rules are sometimes counterintuitive. For example,
    75  `foo: false` is not the same as `foo: "false"`. Large integers like `foo: 12345678`
    76  will get converted to scientific notation in some cases.
    77  
    78  The easiest way to avoid type conversion errors is to be explicit about strings,
    79  and implicit about everything else. Or, in short, _quote all strings_.
    80  
    81  Often, to avoid the integer casting issues, it is advantageous to store your
    82  integers as strings as well, and use `{{ int $value }}` in the template to convert
    83  from a string back to an integer.
    84  
    85  In most cases, explicit type tags are respected, so `foo: !!string 1234` should
    86  treat `1234` as a string. _However_, the YAML parser consumes tags, so the type
    87  data is lost after one parse.
    88  
    89  ## Consider How Users Will Use Your Values
    90  
    91  There are four potential sources of values:
    92  
    93  - A chart's `values.yaml` file
    94  - A values file supplied by `helm install -f` or `helm upgrade -f`
    95  - The values passed to a `--set` or `--set-string` flag on `helm install` or `helm upgrade`
    96  - The content of a file passed to `--set-file` flag on `helm install` or `helm upgrade`
    97  
    98  When designing the structure of your values, keep in mind that users of your
    99  chart may want to override them via either the `-f` flag or with the `--set`
   100  option.
   101  
   102  Since `--set` is more limited in expressiveness, the first guidelines for writing
   103  your `values.yaml` file is _make it easy to override from `--set`_.
   104  
   105  For this reason, it's often better to structure your values file using maps.
   106  
   107  Difficult to use with `--set`:
   108  
   109  ```yaml
   110  servers:
   111    - name: foo
   112      port: 80
   113    - name: bar
   114      port: 81
   115  ```
   116  
   117  The above cannot be expressed with `--set` in Helm `<=2.4`. In Helm 2.5, the
   118  accessing the port on foo is `--set servers[0].port=80`. Not only is it harder
   119  for the user to figure out, but it is prone to errors if at some later time the
   120  order of the `servers` is changed.
   121  
   122  Easy to use:
   123  
   124  ```yaml
   125  servers:
   126    foo:
   127      port: 80
   128    bar:
   129      port: 81
   130  ```
   131  
   132  Accessing foo's port is much more obvious: `--set servers.foo.port=80`.
   133  
   134  ## Document 'values.yaml'
   135  
   136  Every defined property in 'values.yaml' should be documented. The documentation string should begin with the name of the property that it describes, and then give at least a one-sentence description.
   137  
   138  Incorrect:
   139  
   140  ```
   141  # the host name for the webserver
   142  serverHost = example
   143  serverPort = 9191
   144  ```
   145  
   146  Correct:
   147  
   148  ```
   149  # serverHost is the host name for the webserver
   150  serverHost = example
   151  # serverPort is the HTTP listener port for the webserver
   152  serverPort = 9191
   153  
   154  ```
   155  
   156  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.