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:
Value | Description |
---|---|
false (Default) | The The top level keys in |
true | The All keys from In the case of a conflict where there is a matching key in |
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 withhelm template
. Thebuilder
key specifies the values from the Helm chartvalues.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 thebuilder
key because values in thebuilder
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 Helmrequired
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 thebuilder
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