HelmChart v1 (Deprecated)

important

The HelmChart custom resource apiVersion: kots.io/v1beta1 is deprecated. For installations with Replicated KOTS v1.99.0 and later, use the HelmChart custom resource with apiVersion: kots.io/v1beta2 instead. See HelmChart v2.

Each Helm chart .tgz archive in a release requires a unique HelmChart custom resource. The HelmChart custom resource provides the Replicated installer with the instructions needed to process and deploy the given Helm chart.

The HelmChart custom resource also generates a list of required images for the chart, which is necessary for the following use cases:

Air gap installations with the Helm CLI or with a Replicated installer
Online installations with a Replicated installer where the user will push images to a local image registry
Online or air gap installations that use the Security Center (Beta) to scan and report on Helm chart images

For more information, see About Distributing Helm Charts with KOTS.

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

Properties

chart

The chart key allows for a mapping between the data in this definition and the chart archive itself. You can create multiple HelmChart resources that all reference a single chart archive.

Property Description

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.

Property	Description
`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`	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, add a separate HelmChart custom resource with a unique release name for each instance. 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.

chart.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, add a separate HelmChart custom resource with a unique release name for each instance.

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 switch a Helm chart in an existing installation from useHelmInstall: false to useHelmInstall: true. If a user previously installed the Helm chart using apiVersion: kots.io/v1beta1 and useHelmInstall: false, the installer displays the following error when a release changes the value of useHelmInstall: deployment method for chart release <release_name> has changed.

To move these installations to HelmChart v2 without reinstalling, see Migrate from HelmChart v1 with useHelmInstall: false in Migrate existing installations to HelmChart v2.

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

weight

The weight field is not supported for HelmChart custom resources with useHelmInstall: false.

For installations with a Replicated installer, weight specifies the installation order of the Helm charts in the release. Charts are installed by weight in ascending order with lower weights first. weight also determines the uninstall order, where charts are uninstalled by weight in descending order with higher weights first.

weight controls only the order in which charts are installed. By default, the installer does not wait for a chart's resources to be ready before it installs the next chart. To wait for readiness, add --wait to the chart's helmUpgradeFlags.

For installations with the Helm CLI, the Vendor Portal and the Replicated Enterprise Portal use the weight property to order the list of charts in the installation and update instructions. For more information, see Chart installation order in Install with Helm and View Install and Update Instructions in Log in to and use the Enterprise Portal.

Supported values: Positive or negative integers. Default: 0

helmUpgradeFlags

The helmUpgradeFlags field is not supported for HelmChart custom resources with useHelmInstall: false.

Specifies additional flags to pass to the helm upgrade command. The Replicated installer runs helm upgrade for all deployments, not just upgrades, by specifying the --install flag.

The Replicated installer passes these flags in addition to the flags it passes by default. The values specified in this field take precedence if the installer already passes the same flag.

Template functions can parse the helmUpgradeFlags attribute. For more information, see About Replicated template functions.

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.

note

KOTS, Embedded Cluster v2, and Embedded Cluster v3 do not pass --wait or --wait-for-jobs to Helm for application charts by default. The installer installs charts in the order set by weight and starts the next chart as soon as Helm returns for the previous one, without waiting for its resources to be ready. Helm still runs the chart's hooks and waits for hook Jobs to complete before it returns.

If a chart depends on resources from an earlier chart being ready (for example, an operator that must be running before a later chart creates its custom resources), add --wait to the helmUpgradeFlags of the earlier chart. If the later chart also depends on Jobs in the earlier chart completing, add --wait-for-jobs as well.

When you add --wait, also check the timeout. KOTS and Embedded Cluster v2 use a default timeout of 3600s. Embedded Cluster v3 uses a default timeout of 5m. If a chart can take longer than that to become ready, add --timeout with a longer value.

With --wait, Helm waits for all non-hook resources to be ready before it runs post-install or post-upgrade hooks. Do not add --wait to a chart where a non-hook resource depends on a resource created by a hook (for example, a Deployment with an init container that waits for a database custom resource created by a post-install hook). This creates a deadlock where the install times out.

Examples

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

Wait for the chart's resources to be ready and its Jobs to complete before the next chart installs, with a 20 minute timeout:

helmUpgradeFlags:
  - --wait
  - --wait-for-jobs
  - --timeout
  - 1200s

values

Use the values key to set or delete values in the corresponding Helm chart's values.yaml file. Any values that you include in the values key must match values in the Helm chart values.yaml. For example, spec.values.images.pullSecret in the HelmChart custom resource matches images.pullSecret in the Helm chart values.yaml.

During installation or upgrade with a Replicated installer, the installer merges values with the Helm chart values.yaml in the chart archive.

Only include values in the values key that you want to set or delete.

Example

# HelmChart custom resource

apiVersion: kots.io/v1beta1
kind: HelmChart
metadata:
  name: samplechart
spec:
  values:
    postgresql:
      enabled: repl{{ ConfigOptionEquals `postgres_type` `embedded_postgres`}}

exclude

When the installer processes your release, it excludes any Helm chart if the output of the exclude field is true.

Template functions can parse the exclude attribute. See About Replicated template functions.

optionalValues

Use the optionalValues key to set values in the Helm chart values.yaml file when a conditional statement evaluates to true. For example, a customer including an optional application component might need Helm chart values related to that component.

optionalValues includes the following properties:

Property	Description
`optionalValues.when`	Defines a conditional statement that must evaluate to true for the Helm chart to apply the values in `optionalValues.values`. The Replicated installer defers evaluation of the conditional in `optionalValues.when` until render time in the customer environment.
`optionalValues.recursiveMerge`	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`. When `optionalValues.recursiveMerge` is true, the installer includes all keys from `values` and `optionalValues`. 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`. By default, `optionalValues.recursiveMerge` is false. For an example, see Recursive merge on this page.
`optionalValues.values`	Array of key value pairs to set in the Helm chart when the specified condition is true. Supports static values and Replicated template functions.

Examples

Set optional values with Replicated template functions

# HelmChart custom resource

apiVersion: kots.io/v1beta1
kind: HelmChart
spec:
  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.

Recursive merge

The following HelmChart custom resource has both values and optionalValues:

# HelmChart custom resource
apiVersion: kots.io/v1beta2
kind: HelmChart
spec:
  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 associated Helm chart values.yaml file defines these key value pairs:

# Helm chart values.yaml
favorite:
  drink:
    hot: coffee
    cold: soda
  dessert: pie

The associated Helm chart has the following templates/configmap.yaml file:

# templates/configmap.yaml
apiVersion: v1
kind: 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 false, the ConfigMap for the deployed application includes the following key value pairs:

# templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
data:
  favorite_day: null
  favorite_dessert: pie
  favorite_drink_cold: lemonade
  favorite_drink_hot: coffee

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

# templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
data:
  favorite_day: saturday
  favorite_dessert: ice cream
  favorite_drink_cold: lemonade
  favorite_drink_hot: tea

namespace

The namespace key specifies an alternative namespace to install the Helm chart. By default, for Embedded Cluster v2 and KOTS existing cluster installations, KOTS installs the chart in the same namespace as the Admin Console. For Embedded Cluster v3 installations, Embedded Cluster installs the chart in a namespace named <your-app-slug> by default.

Template functions can parse the namespace attribute. For more information about template functions, see About Replicated template functions.

For Embedded Cluster v2 and KOTS existing cluster installations, 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.

builder

The builder key contains the minimum Helm values required so that the output of helm template exposes all container images needed to install the chart in an air-gapped environment.

The Replicated Vendor Portal uses the Helm values in the builder key to run helm template on the chart. It then parses the output to generate a list of required images.

The Vendor Portal then uses this list of images to do the following:

Create the Helm CLI air gap installation instructions that are automatically made available to customers in the Enterprise Portal or Download Portal.
Build the .airgap bundle for a release to support air gap installations with a Replicated installer (Embedded Cluster, KOTS, kURL).
Determine which images to scan and report on in the Security Center (Beta).

You must configure the builder key to support the following installation types:

Air gap installations with a Replicated installer (Embedded Cluster, KOTS, kURL)
Air gap installations with the Helm CLI
Online installations with KOTS or kURL where the user will push images to their own local image registry

Requirements

The builder key has the following requirements and recommendations:

Replicated recommends that you include only the minimum Helm values in the builder key required to template the Helm chart with the correct image tags.
Use only static, or hardcoded, values in the builder key. You can't use template functions in the builder key because values in the builder key are not rendered in a customer environment.
Any required Helm values that need to be set to render the chart templates must have a value in the builder key. For more information about the Helm required function, see Using the 'required' function in the Helm documentation.
Specify kubeVersion in the root Helm chart. The Vendor Portal renders Helm charts with the minimum Kubernetes minor version that satisfies the kubeVersion in the root Helm chart. For example, if the chart specifies kubeVersion: >=1.24.1, then it's rendered with Kubernetes 1.25.0. If this fails or if a kubeVersion is not specified in the root Helm chart, then the Vendor Portal attempts to render the chart with each supported minor version of Kubernetes up to the latest version.
Every conditional template that uses a unique image must render with the values in the builder key. For example, if a self-signed certificate Job renders only when tls.mode is self-signed, set tls.mode: self-signed in the builder key. This makes the template render so that the Vendor Portal includes its image.
The Vendor Portal renders the chart with a single set of values: the chart's default values plus the values in the builder key. It ignores the values and optionalValues keys when it builds the image list, so a value set only in values does not cause a conditional template to render.
If two templates are mutually exclusive, such as the two branches of an if/else on the same value, they can't both render in a single pass. Set the builder key to render one branch, and list the images from the other branch in the additionalImages field of the Application custom resource. For more information about when to use additionalImages, see When to use additionalImages in Define additional images.
If the builder values don't render an image and additionalImages doesn't list it, the Vendor Portal omits the image from the release's image list. The release still builds successfully, and the Vendor Portal doesn't show a warning. When a customer enables the feature that uses the image, the Pods for that feature fail to start with an image pull error. This affects air gap installations and installations where the customer pushes images to their own registry.

Example

Many applications include or exclude images based on a given condition.

For example, a Helm chart might include a conditional PostgreSQL Deployment, as shown in the following Helm template:

{{- if .Values.postgresql.enabled }}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgresql
  labels:
    app: postgresql
spec:
  selector:
    matchLabels:
      app: postgresql
  template:
    metadata:
      labels:
        app: postgresql
    spec:
      containers:
      - name: postgresql
        image: "postgres:10.17"
        ports:
        - name: postgresql
          containerPort: 80
# ...
{{- end }}

To include the postgresql image in the air gap bundle, add postgresql.enabled to the builder key of the HelmChart custom resource and set it to true:

apiVersion: kots.io/v1beta2
kind: HelmChart
metadata:
  name: samplechart
spec:
  chart:
    name: samplechart
    chartVersion: 3.1.7
  values:
    postgresql:
      enabled: repl{{ ConfigOptionEquals "postgres_type" "embedded_postgres"}}
  builder:
    postgresql:
      enabled: true

Example​

Properties​

chart​

helmVersion​

useHelmInstall​

weight​

helmUpgradeFlags​

Examples​

values​

Example​

exclude​

optionalValues​

Examples​

Set optional values with Replicated template functions​

Recursive merge​

namespace​

builder​

Requirements​

Example​

On this page

Example

Properties

chart

helmVersion

useHelmInstall

weight

helmUpgradeFlags

Examples

values

Example

exclude

optionalValues

Examples

Set optional values with Replicated template functions

Recursive merge

namespace

builder

Requirements

Example