Configuring Optional Value Keys

The Helm chart values.yaml file is not a static mapping in an application. It is possible, for native Helm and Replicated Helm installations, to either override values or include values when certain conditions are met.

Override Values

If the Helm chart values.yaml contains a static value that must be overridden when deploying using the Replicated KOTS, set the value to "null" (including the quotation marks) in the HelmChart custom resource manifest file.

Typically this situation happens when you are including a community chart as a dependency in your own chart. You cannot control how the community chart is built and structured, and you might want to change some of the default behavior that the community chart does not easily expose. For more information, see Deleting a Default Key in the Helm documentation.

Include Values

Some advanced use cases involve writing values to a values file only if there is a value to apply. For example, if a customer has the option to configure a different value than the default value in your file, such as setting the database option they want to use. You can include an optional value key so that your application can dynamically include it based on a when condition.

For more information about the optionalValues property, see optionalValues in the HelmChart reference.

For example, in the Bitnami Wordpress chart.yaml. file, there is a reference to mariadb. This reference is configured through the values.yaml file:

mariadb:
  ## @param mariadb.enabled Deploy a MariaDB server to satisfy the applications database requirements
  ## To use an external database set this to false and configure the `externalDatabase.*` parameters
  ##
  enabled: true
...
## External Database Configuration
## All of these values are only used if `mariadb.enabled=false`
##
externalDatabase:
  ## @param externalDatabase.host External Database server host
  ##
  host: localhost
  ## @param externalDatabase.port External Database server port
  ##
  port: 3306
  ## @param externalDatabase.user External Database username
  ##
  user: bn_wordpress
  ## @param externalDatabase.password External Database user password
  ##
  password: ""
  ## @param externalDatabase.database External Database database name
  ##
  database: bitnami_wordpress

If a user wants to configure an external database, you can enable this dynamically through your deployment by adding an optionalValues section to the kind: HelmChart custom resource, instead of attempting to modify the render logic in the Helm chart.

The optionalValues section includes a when condition that instructs KOTS how to determine if these keys should be merged. It also includes a recursiveMerge field that defines how to merge the dataset.

For example, the HelmChart custom resource can be configured as follows:

apiVersion: kots.io/v1beta1
kind: HelmChart
metadata:
  name: wordpress
spec:
  # chart identifies a matching chart from a .tgz
  chart:
    name: wordpress
    chartVersion: 15.3.2

  # values are used in the customer environment, as a pre-render step
  # these values will be supplied to helm template
  values:
    mariadb:
      enabled: repl{{ ConfigOptionEquals `mariadb_type` `embedded`}}

  optionalValues:
    - when: "repl{{ ConfigOptionEquals `mariadb_type` `external`}}"
      recursiveMerge: false
      values:
        externalDatabase:
          host: "repl{{ ConfigOption `external_db_host`}}"
          user: "repl{{ ConfigOption `external_db_user`}}"
          password: "repl{{ ConfigOption `external_db_password`}}"
          database: "repl{{ ConfigOption `external_db_database`}}"
          port: "repl{{ ConfigOption `external_ db_port`}}"


  # builder values provide a way to render the chart with all images
  # and manifests. this is used in replicated to create airgap packages
  builder:
    mariadb:
      enabled: true

The HelmChart YAML above results in the following values.yaml if a user selects a mariadb_type of external:

mariadb:
  enabled: false
externalDatabase:
  host: "repl{{ ConfigOption `external_db_host`}}"
  user: "repl{{ ConfigOption `external_db_user`}}"
  password: "repl{{ ConfigOption `external_db_password`}}"
  database: "repl{{ ConfigOption `external_db_database`}}"
  port: "repl{{ ConfigOption `external_db_port`}}"

The HelmChart YAML above results in the following values.yaml if the user selects a mariadb_type of embedded:

mariadb:
  enabled: true

Example: Recursive Merge

The recursiveMerge boolean defines how Replicated KOTS merges the values and optionalValues datasets when the conditional statement in the when field is true.

Then, the admin console uses the values from this merged dataset and from the Helm chart values.yaml file when deploying the application.

For more information about the recursiveMerge field, see optionalValues in the HelmChart reference.

For example, a HelmChart custom resource manifest file defines the following datasets in the values and optionalValues fields:

values:
  favorite:
    drink:
      hot: tea
      cold: soda
    dessert: ice cream
    day: saturday

optionalValues:
  - when: '{{repl ConfigOptionEquals "example_config_option" "1" }}'
    recursiveMerge: false
    values:
      example_config_option:
        enabled: true
      favorite:
        drink:
          cold: lemonade

The values.yaml file for the associated Helm chart defines the following key value pairs:

favorite:
  drink:
    hot: coffee
    cold: soda
  dessert: pie

The templates/configmap.yaml file for the Helm chart maps these values to the following fields:

apiVersion: v1
kind: ConfigMap
metadata:
  name: test-configmap
data:
  favorite_day: {{ .Values.favorite.day }}
  favorite_dessert: {{ .Values.favorite.dessert }}
  favorite_drink_cold: {{ .Values.favorite.drink.cold }}
  favorite_drink_hot: {{ .Values.favorite.drink.hot }}

When recursiveMerge is set to false in the HelmChart custom resource manifest file, the ConfigMap for the deployed application includes the following key value pairs:

favorite_day: null
favorite_dessert: pie
favorite_drink_cold: lemonade
favorite_drink_hot: coffee

In this case, the top level keys in optionalValues overwrite the top level keys in values.

Then, the admin console uses the values from the Helm chart values.yaml to populate the remaining fields in the ConfigMap: favorite_day, favorite_dessert, and favorite_drink_hot.

When recursiveMerge is set to true, the ConfigMap for the deployed application includes the following key value pairs:

favorite_day: saturday
favorite_dessert: ice cream
favorite_drink_cold: lemonade
favorite_drink_hot: tea

In this case, all keys from values and optionalValues are included in the merged dataset. Both include favorite: > drink: > cold:, so the merged dataset uses lemonade from optionalValues.