Set Helm Values with Replicated HelmChart

This topic describes how to use the Replicated HelmChart custom resource to set and delete values in values.yaml files for Helm charts. The information in this topic applies to applications installed with a Replicated installer (Embedded Cluster, KOTS, kURL).

Overview

The HelmChart custom resource values and optionalValues keys create a mapping between the Replicated installer and the corresponding Helm chart's values.yaml file. This allows you to set or delete Helm values during installation or upgrade, without having to make any changes to the Helm chart itself.

Common use cases for the values and optionalValues keys include:

• Setting Helm values based on user-supplied values from the Admin Console configuration page
• Setting Helm values based on the user's license entitlements
• Setting certain Helm values only when a given condition is met
• Excluding a default value key from the Helm chart values.yaml file when the user installs with a Replicated installer

Set Static Values

You can use static values to set Helm values for Replicated installations, without affecting values for any installations that use the Helm CLI.

For example, the following Helm chart values.yaml file contains replicatedOnlyValue.enabled, which is set to false by default:

# Helm chart values.yaml
replicatedOnlyValue:
  enabled: false

The following HelmChart custom resource contains a mapping to replicatedOnlyValue.enabled in its values key, which is set to true:

# Replicated HelmChart custom resource

apiVersion: kots.io/v1beta2
kind: HelmChart
metadata:
  name: samplechart
spec:
  chart:
    name: samplechart
    chartVersion: 3.1.7
  
  releaseName: samplechart-release-1

  values:
    replicatedOnlyValue:
      enabled: true

During installation or upgrade with a Replicated installer, the installer sets replicatedOnlyValue.enabled in the Helm chart values.yaml file to true. For installations with the Helm CLI, replicatedOnlyValue.enabled remains false.

Set Values with Replicated Template Functions

You can use Replicated template functions to render values like customer-specific license field values, user-provided configuration values, or information about the customer environment. For more information about working with template functions, see About Replicated Template Functions.

The following examples show how to use Replicated template functions in the values key to render config- and license-specific values:

Config Context Example

Using Replicated template functions in the Config context allows you to set Helm values based on user-supplied values from the Admin Console configuration page.

The following Helm chart values.yaml file contains postgresql.enabled, which is set to false:

# Helm chart values.yaml
postgresql:
  enabled: false

The following HelmChart custom resource contains a mapping to postgresql.enabled in its values key:

# HelmChart custom resource

apiVersion: kots.io/v1beta2
kind: HelmChart
metadata:
  name: samplechart
spec:
  chart:
    name: samplechart
    chartVersion: 3.1.7
  
  releaseName: samplechart-release-1

  values:
    postgresql:
      enabled: repl{{ ConfigOptionEquals `postgres_type` `embedded_postgres`}}

The values.postgresql.enabled field in the HelmChart custom resource above uses the Replicated ConfigOptionEquals template function to evaluate the user's selection for a postgres_type configuration option.

During installation or upgrade, the template function is rendered to true or false based on the user's selction. Then, the Replicated installer sets the matching postgresql.enabled value in the Helm chart values.yaml file accordingly.

License Context Example

Using Replicated template functions in the License context allows you to set Helm values based on the unique license file used for installation or upgrade.

For example, the following HelmChart custom resource uses the Replicated LiencseFieldValue template function to evaluate if the license has the boolean newFeatureEntitlement field set to true:

# HelmChart custom resource

apiVersion: kots.io/v1beta2
kind: HelmChart
metadata:
  name: samplechart
spec:
  chart:
    name: samplechart
    chartVersion: 3.1.7
  
  releaseName: samplechart-release-1

  values:
    newFeature:
      enabled: repl{{ LicenseFieldValue "newFeatureEntitlement" }}

During installation or upgrade, the LicenseFieldValue template function is rendered based on the user's license. Then, the Replicated installer sets the matching newFeature.enabled value in the Helm chart values.yaml file accordingly.

Conditionally Set Values

The optionalValues key can be used to set values in the Helm chart values.yaml file when a given conditional statement evaluates to true. For example, if a customer chooses to include an optional application component in their deployment, it might be necessary to include Helm chart values related to the optional component.

optionalValues includes the following properties:

• optionalValues.when: Defines a conditional statement using Replicated template functions. If optionalValues.when evaluates to true, then the values specified in optionalValues are set.

• optionalValues.recursiveMerge: Defines how optionalValues is merged with values.

• optionalValues.values: An array of key-value pairs.

For example, the following HelmChart custom resource uses the optionalValues key and the ConfigOptionEquals template function to set user-supplied values for an external MariaDB database:

# HelmChart custom resource

apiVersion: kots.io/v1beta2
kind: HelmChart
metadata:
  name: wordpress
spec:
  chart:
    name: wordpress
    chartVersion: 15.3.2

  releaseName: sample-release-1

  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`}}"

During installation, the Replicated installer renders the template functions and sets the externalDatabase values in the HelmChart values.yaml file only when the user selects the external option for mariadb_type.

About Recursive Merge for optionalValues

The optionalValues.recursiveMerge boolean defines how the Replicated installer merges values and optionalValues:

• When optionalValues.recursiveMerge is false, the top level keys in optionalValues override the top level keys in values. By default, optionalValues.recursiveMerge is set to false.

• When optionalValues.recursiveMerge is true, all keys from values and optionalValues are included. In the case of a conflict where there is a matching key in optionalValues and values, the Replicated installer uses the value of the key from optionalValues.

For example, the following HelmChart custom resource has both values and optionalValues:

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, 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 override the top level keys in values.

KOTS then 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 merged. Because both include favorite.drink.cold, KOTS uses lemonade from optionalValues.

Delete a Default Key

If the Helm chart values.yaml contains a static value that must be deleted when deploying with KOTS, you can set the value to "null" (including the quotation marks) in the values key of the HelmChart custom resource.

A common use case for deleting default value keys is when you include a community Helm chart as a dependency. Because you cannot control how the community chart is built and structured, you might want to change some of the default behavior.

For example, the following HelmChart custom resource sets an exampleKey value to "null" when the chart is deployed with KOTS:

# KOTS HelmChart custom resource

apiVersion: kots.io/v1beta2
kind: HelmChart
metadata:
  name: samplechart
spec:
  chart:
    name: samplechart
    chartVersion: 3.1.7
  
  releaseName: samplechart-release-1

  values:
    exampleKey: "null"

For more information about using a null value to delete a key, see Deleting a Default Key in the Helm documentation.