Skip to main content

HelmChart v2

Introduced in Replicated KOTS v1.99.0

HelmChart custom resources are required for Replicated KOTS to process and deploy Helm charts for the supported Helm installation types. For more information, see About Distributing Helm Charts with KOTS.

The HelmChart custom resource manifest file references a required .tgz archive of the Helm chart and provides the necessary instructions for processing and preparing the chart for deployment. To deploy multiple instances of the same Helm chart, you must add an additional HelmChart custom resource for each instance. However, only one .tgz of the Helm chart needs to be included in the release.

Example​

The following is an example manifest file for the HelmChart v2 custom resource:

apiVersion: kots.io/v1beta2
kind: HelmChart
metadata:
  name: samplechart
spec:
  # chart identifies a matching chart from a .tgz
  chart:
    name: samplechart
    chartVersion: 3.1.7
  
  releaseName: samplechart-release-1

  exclude: "repl{{ ConfigOptionEquals `include_chart` `include_chart_no`}}"

  # weight determines the order that charts are applied, with lower weights first.
  weight: 42

  # helmUpgradeFlags specifies additional flags to pass to the `helm upgrade` command.
  helmUpgradeFlags:
    - --skip-crds
    - --no-hooks
    - --timeout
    - 1200s
    - --history-max=15

  # values are used in the customer environment as a pre-render step
  # these values are supplied to helm template
  values:
    postgresql:
      enabled: repl{{ ConfigOptionEquals `postgres_type` `embedded_postgres`}}

  optionalValues:
  - when: "repl{{ ConfigOptionEquals `postgres_type` `external_postgres`}}"
    recursiveMerge: false
    values:
      postgresql:
        postgresqlDatabase: "repl{{ if ConfigOptionEquals `postgres_type` `external_postgres`}}repl{{ ConfigOption `external_postgres_database`}}repl{{ end}}"
        postgresqlUsername: "repl{{ if ConfigOptionEquals `postgres_type` `external_postgres`}}repl{{ ConfigOption `external_postgres_username`}}repl{{ end}}"
        postgresqlHost: "repl{{ if ConfigOptionEquals `postgres_type` `external_postgres`}}repl{{ ConfigOption `external_postgres_host`}}repl{{ end}}"
        postgresqlPassword: "repl{{ if ConfigOptionEquals `postgres_type` `external_postgres`}}repl{{ ConfigOption `external_postgres_password`}}repl{{ end}}"
        postgresqlPort: "repl{{ if ConfigOptionEquals `postgres_type` `external_postgres`}}repl{{ ConfigOption `external_postgres_port`}}repl{{ end}}"
  # adds backup labels to postgresql if the license supports snapshots
  - when: "repl{{ LicenseFieldValue `isSnapshotSupported` }}"
    recursiveMerge: true
    values:
      postgresql:
        commonLabels:
          kots.io/backup: velero
          kots.io/app-slug: my-app
        podLabels:
          kots.io/backup: velero
          kots.io/app-slug: my-app  

  # namespace allows for a chart to be installed in an alternate namespace to
  # the default
  namespace: samplechart-namespace

  # builder values render the chart with all images and manifests.
  # builder is used to create `.airgap` packages and to support end users
  # who use private registries
  builder:
    postgresql:
      enabled: true

chart​

The chart key allows for a mapping between the data in this definition and the chart archive itself. More than one kind: HelmChart can reference a single chart archive, if different settings are needed.

chart.name​

The name of the chart. This value must exactly match the name field from a Chart.yaml in a .tgz chart archive that is also included in the release. If the names do not match, then the installation can error or fail.

chart.chartVersion​

The version of the chart. This value must match the version field from a Chart.yaml in a .tgz chart archive that is also included in the release.

releaseName​

Specifies the release name to use when installing this instance of the Helm chart. Defaults to the chart name.

The release name must be unique across all charts deployed in the namespace. To deploy multiple instances of the same Helm chart in a release, you must add an additional HelmChart custom resource with a unique release name for each instance of the Helm chart.

Must be a valid Helm release name that matches regex ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ and is no longer than 53 characters.

weight​

Determines the order in which KOTS applies the Helm chart. Charts are applied by weight in ascending order, with lower weights applied first. Supported values: Positive or negative integers. Default: 0

In KOTS v1.99.0 and later, weight also determines the order in which charts are uninstalled. Charts are uninstalled by weight in descending order, with higher weights uninstalled first. For more information about uninstalling applications, see remove in kots CLI.

For more information, see Defining Installation Order for Helm Charts.

helmUpgradeFlags​

Specifies additional flags to pass to the helm upgrade command for charts. Applies only when the HelmChart custom resource has useHelmInstall: true. These flags are passed in addition to any flags Replicated KOTS passes by default. The values specified here take precedence if KOTS already passes the same flag. The helmUpgradeFlags attribute can be parsed by template functions. For more information about template functions, see About template function contexts.

KOTS uses helm upgrade for all deployments of an application, not just upgrades, by specifying the --install flag. For non-boolean flags that require an additional argument, such as --timeout 1200s, you must use an equal sign (=) or specify the additional argument separately in the array.

Example:

helmUpgradeFlags:
  - --timeout
  - 1200s
  - --history-max=15

values​

The values key allows for values to be changed in the chart. It also can create a mapping between the Replicated admin console configuration screen and the values. This mapping makes it possible to use the configuration screen in the admin console to control the Helm values.yaml file. For more information about the configuration screen, see About the Configuration Screen.

The keys below values must map exactly to the keys in your values.yaml. Only include the keys below values that you want to change. These are merged with the values.yaml in the chart archive.

To exclude a value that is set in the Helm chart values.yaml, set the value equal to the string "null" (with quotes) in the values section of the HelmChart custom resource.

For more options, see the Allow deletion of a previous values file key pull request in the Helm repository in GitHub.

exclude​

The attribute is a value for making optional charts. The exclude attribute can be parsed by template functions.

When Replicated KOTS processes Helm charts, it excludes the entire chart if the output of the exclude field can be parsed as a boolean evaluating to true.

For more information about optional charts, template functions, and how KOTS processes Helm charts, see:

optionalValues​

The optionalValues array supports advanced use cases where value overwrites must be dependent on a given condition evaluating to true.

Not all Helm charts treat "" and missing as the same value. If you need to have a value set that is always optional, and an empty string does not provide the same functionality as "not set", use the optionalValues key.

For more information about using optionalValues, see Including Optional Value Keys.

optionalValues[].when​

The when field in optionalValues provides a string-based method that is evaluated by template functions. The when field defers evaluation of the conditional to render time in the customer environment.

To write the when conditional statement, use template functions. The following example shows a conditional statement for selecting a database option on the admin console configuration screen:

optionalValues:
  - when: "repl{{ ConfigOptionEquals `postgres_type` `external_postgres`}}"

For more information about using optional values, see Configuring Optional Value Keys.

For more information about the syntax for template functions, see About Template Function Contexts.

optionalValues[].recursiveMerge​

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

The admin console uses the values from this merged dataset and from the Helm chart values.yaml file when deploying the application. For an example of recursive merge, see Example: Recursive Merge in Configuring Optional Value Keys.

The following table describes how values and optionalValues are merged based on the value of the recursiveMerge boolean:

ValueDescription
false (Default)

The values and optionalValues fields from the HelmChart custom resource manifest are not merged recursively.

The top level keys in optionalValues overwrite the top level keys in values.

true

The values and optionalValues fields from the HelmChart custom resource manifest are merged recursively.

All keys from values and optionalValues are included in the merged dataset.

In the case of a conflict where there is a matching key in optionalValues and values, the merged dataset uses the value of the key from optionalValues.

namespace​

The namespace key specifies an alternative namespace where Replicated KOTS installs the Helm chart. Default: The Helm chart is installed in the same namespace as the admin console. The namespace attribute can be parsed by template functions. For more information about template functions, see About template function contexts.

If you specify a namespace in the HelmChart namespace field, you must also include the same namespace in the additionalNamespaces field of the Application custom resource manifest file. KOTS creates the namespaces listed in the additionalNamespaces field during installation. For more information, see additionalNamespaces in the Application reference.

builder​

The builder key is required for the following use cases:

  • To create an .airgap bundle for a release that uses Helm charts, the Replicated vendor portal renders templates of the Helm charts with helm template. The builder key specifies the values from the Helm chart values.yaml file that the vendor portal uses to create the .airgap bundle. For more information, see Air Gap Installations in About Distributing Helm Charts with KOTS.

  • To support online installations that use a local private registry, the builder field renders the Helm chart with all of the necessary images so that KOTS knows where to pull the images.

    By default, pushing images to a local registry is enabled for all installations. A user in an online environment might disable the ability to push images to a local registry only if an external process is responsible for pushing all images to the registry. For more information, see Using Private Registries.

The builder key has the following requirements and recommendations:

  • Replicated recommends that you include only the minimum Helm values in the builder key that are required to template the Helm chart with the correct image tags.
  • Use only static, or hardcoded, values in the builder key. You cannot use template functions in the builder key because values in the builder key are not rendered in a customer environment.
  • Any Helm values entries that are required for rendering Helm chart templates must have a value supplied in the builder key. For more information about the Helm required function, see Using the 'required' function in the Helm documentation.
  • Use the same builder configuration to support the use of local registries in both online and air gap installations. If you already configured the builder key to support air gap installations, then no additional configuration is required.

Example:

The following example demonstrates how to add a conditional postgresql resource to the builder key.

postgresql is defined as a conditional resource in the values key of the HelmChart custom resource:

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

As shown above, postgresql is included only when the user selects the embedded_postgres option.

To ensure this conditional postgresql resource is included in the installation files, add the same postgresql value to the builder key with enabled set to true:

  builder:
    postgresql:
      enabled: true