Skip to main content

HelmChart v1

note

The HelmChart custom resource apiVersion: kots.io/v1beta1 is deprecated. Replicated recommends that you add a HelmChart with apiVersion: kots.io/v1beta2 for each Helm chart in your releases. See Migrating from v1beta1 to v1beta2 in Configuring the HelmChart Custom Resource.

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 v1 custom resource:

apiVersion: kots.io/v1beta1
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`}}"

  # helmVersion identifies the Helm Version used to render the chart. Default is v3.
  helmVersion: v3

  # useHelmInstall identifies the kots.io/v1beta1 installation method
  useHelmInstall: true

  # weight determines the order that charts with "useHelmInstall: true" 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 will be 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}}"

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

  # builder values provide a way to render the chart with all images
  # and manifests. this is used in Replicated to create `.airgap` packages
  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.

chart.releaseName​

Introduced in Replicated KOTS v1.73.0

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.

helmVersion​

Identifies the Helm Version used to render the chart. Acceptable values are v2 or v3. v3 is the default when no value is specified.

note

Support for Helm v2, including security patches, ended on November 13, 2020. If you specified helmVersion: v2 in any HelmChart custom resources, update your references to v3. By default, KOTS uses Helm v3 to process all Helm charts.

useHelmInstall​

Identifies the method that KOTS uses to install the Helm chart:

  • useHelmInstall: true: KOTS uses Kustomize to modify the chart then repackages the resulting manifests to install. This was previously referred to as the native Helm installation method.

  • useHelmInstall: false: KOTS renders the Helm templates and deploys them as standard Kubernetes manifests using kubectl apply. This was previously referred to as the Replicated Helm installation method.

    note

    You cannot migrate existing Helm charts in existing installations from the useHelmInstall: false installation method to a different method. If KOTS already installed the Helm chart previously in the environment using a HelmChart custom resource with apiVersion: kots.io/v1beta1 and useHelmInstall: false, then KOTS does not attempt to install the chart using a different method and displays the following error message: Deployment method for chart <chart_name> has changed.

    To change the installation method from useHelmInstall: false to a different method, the user must reinstall your application in a new environment.

For more information about how KOTS deploys Helm charts when useHelmInstall is true or false, see About Distributing Helm Charts with KOTS.

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.

The weight field is not supported for Helm charts installed with HelmChart custom resources that have apiVersion: kots.io/v1beta1 and useHelmInstall: false.

helmUpgradeFlags​

note

helmUpgradeFlags is available in KOTS v1.75.0 and later.

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​

note

recursiveMerge is available in KOTS v1.38.0 and later.

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​

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.

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.

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