A KOTS HelmChart custom resource enables KOTS to process and deploy Helm charts as part of a Vendor distributed application. HelmChart custom resources are required for KOTS to deploy Helm charts (but not necessary if only raw K8s manifests are being deployed). This spec references a required .tgz export of the Helm chart resources and provides the necessary instructions for processing and preparing the chart for deployment.

Deploying multiple instance of the same chart: Vendors must provide additional HelmChart CR for each instance of the chart that is to be deployed as part of the application. However, only one .tgz of the chart needs to be included in the release.

apiVersion: kots.io/v1beta1
kind: HelmChart
  name: samplechart
  # chart identifies a matching chart from a .tgz
    name: samplechart
    chartVersion: 3.1.7

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

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

    - when: "repl{{ ConfigOptionEquals `postgres_type` `external_postgres`}}"
          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
      enabled: true


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.


The name of the chart. This must match the name field from a Chart.yaml in a .tgz chart archive that’s also included in the release.


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


The values key allows for values to be changed in the chart, or for a mapping between the Replicated Config screen and the values. This makes it possible to use the config screen UI to control the Helm values.yaml.

The keys below values should map exactly to the keys in your values.yaml. Only include the keys that you wish to change, these will be merged with the values.yaml in the chart archive.

To exclude a value that’s set in the values.yaml, set it equal to the string "null" (with quotes), in this section. For more options here, check out the Helm pull request.


The exclude attribute is a template-parsable value for making optional charts. During processing, KOTS will render this field and exclude the entire chart if the output of this field can be parsed as a boolean evaluating to true.


The optionalValues array is provided for advanced use cases to make value overrides completely optional. Not all charts treat "" and missing as the same value. If it’s required to only optionally have a value set, and an empty string does not provide the same functionality as “not set”, then use the values here.

See the guide for using HelmChart optionalValues.


The when field in optionalValues provides a string-based, template-function-evaluated method to defer evaluation of the conditional to render time in the customer environment.


The namespace key allows for a chart to be installed in an alternate namespace. If left blank, the namespace will default to the one into which kotsadm is installed. If an alternate namespace is specified, it is required that the namespace exist or is included in your yaml spec.


The builder key allows for defaults that will be set when Replicated is creating airgap packages. This is an opportunity to ensure that all YAML and images are rendered “on” so they are included.