Supporting helm CLI Installations (Beta)

note

Allowing users to install with the helm CLI is an Beta feature. To enable this feature on your account, log in to your vendor portal account. Select Support > Request a feature, and submit a feature request for "Helm CLI install option".

Some enterprise users prefer or require a Helm chart to install using the helm CLI. This is often because Helm is already approved and the customer has a custom CI pipeline that is compatible with Helm charts. Replicated has introduced Beta support to enable these users to use Helm to install your application.

Prerequisites

To support installations with the helm CLI, you must:

Have an application that contains one or more Helm charts. For information about how to create a release using an existing Helm chart, see Creating Releases with Helm Charts.
If your application uses private images, update your Helm chart to deliver the required image pull secret and to reference the Replicated proxy service. For more information, see Using Private Registries for helm CLI Installations (Beta).

About Supporting helm CLI installations

Using Helm charts to create a release in the vendor portal allows you to package your application one time and support the following application installation methods:

KOTS Install: Install on an existing cluster using the kots CLI or the admin console UI
Embedded Cluster: Install on a cluster provisioned by the Replicated Kubernetes installer
Helm Install: Install on an existing cluster using the helm CLI

To support each of these installations methods from a single release, you use the values field of the Replicated HelmChart custom resource. The values field supports both templated values that are generated by Replicated template functions, as well as static, or hardcoded, values.

Replicated injects any templated values from the HelmChart custom resource values field into the Helm chart values.yaml file. For example, you can use template functions in the HelmChart custom resource to map user-specific values such as license fields or configuration values to the values.yaml file.

For Helm Install installations, Replicated does not inject any static values from the HelmChart custom resource values field into the Helm chart values.yaml file. Any static values in the values field affect only KOTS Install and Embedded Cluster installations, and are ignored for Helm Install installations.

This means that you can include static values in the values field when it is required to make a change in the release that affects only KOTS Install and Embedded Cluster installations. For example, you might need to deliver a Helm chart dependency with your application for only helm CLI installations. You can use static values in the HelmChart custom resource values field to ensure that the dependency is excluded from the release for KOTS Install and Embedded Cluster installations.

For examples of how to use templated and static values in the HelmChart custom resource values field to support all installation methods, see the following procedures:

Delivering the Admin Console with your Application
Using Private Registries

About Installing with the helm CLI

Overview

When you promote an application to a release channel, Replicated extracts any Helm charts included in the release. These charts are pushed as OCI objects to the Replicated private registry at registry.replicated.com. The Helm chart is pushed to the channel.

For example, if your app is named "app", you create a channel named "nightly", and the release promoted contains a Helm chart with name: my-chart in the Chart.yaml, then the chart is pushed to oci://registry.replicated.com/app/nightly/my-chart. The chart version (tag) is read from the Chart.yaml.

This feature supports multiple charts. If your application release contains more than a single chart, all charts are uploaded to the registry.

When a new version of a chart is uploaded, Replicated renders and cache that version for each license when it is pulled the first time.

When a license field changes for a customer, Replicated invalidates all rendered and cached charts. This causes the charts to be rebuilt the next time they are pulled.

The values.yaml in your Chart is rendered with a customer-specific license. Each customer logs in with unique credentials, and our registry is able to identify which customer is pulling the chart. This creates a way to pass custom license fields and other customer-specific data into the values.yaml as defaults, and consume them in Helm templates.

Before Replicated renders the values.yaml, it is not assumed to be a valid YAML format in order to allow flow control and conditional template functions to optionally write some fields to the values.yaml file. Replicated renders template functions in the values.yaml for each customer, as the Helm chart is served to the customer.

Chart Versioning

The chart version is used as the image tag in the OCI registry and must comply with image tag format requirements. A valid tag can contain only lowercase and uppercase letters, digits, underscores, periods, and dashes.

The chart version must also comply with the Semantic Versioning (SemVer) specification. When you run the helm install command without the --version flag, Helm retrieves the list of all available image tags for the chart from the registry and compares them using the SemVer comparison rules described in the SemVer specification. The version that is installed is the version with the largest tag value. For more information about the SemVer specification, see the Semantic Versioning documentation.

Limitations

The helm install method is Beta and has the following limitations:

"Last mile" changes with Kustomize are not supported. All configuration and customization must be done using Helm.
Strict preflights that block application installation are not supported. This is because Helm does not automatically run preflight checks. Preflight checks are supported with helm install, but your users must run the preflight checks manually before installing your application.
Air gap installations are not supported.
Customer adoption is not reported to the vendor portal.
This feature supports multiple charts and Replicated does not wrap or provide any special tooling to manage multiple charts. Replicated recommends that you provide installation instructions with sequenced steps for users to follow to install each chart in the required order.
The Replicated admin console is not included by default when your users install using the helm CLI. For more information about how to include the admin console with your application for helm CLI installations, see Delivering the Admin Console with your Application.

Delivering the Admin Console with your Application

By default, when your users install your application using the helm CLI, the admin console is not included. This section describes how to deliver the admin console alongside your application.

Overview of Delivering the Admin Console

To deliver the admin console with your application for Helm Install installations, include the admin-console Helm chart in the dependencies field of your Chart.yaml file.

When you include the admin-console Helm chart as a dependency, Replicated injects values into the Helm chart values.yaml file when the chart is pulled by your users. These values provide the license ID for the customer, which enables the admin console to authenticate with the image registry and check for updates.

The following shows the formatting of the replicated and license_id fields that Replicated adds to the values.yaml file:

replicated:
  license_id: abcdef123

The functionality of the admin console delivered by the admin-console Helm chart differs from that of the admin console available for KOTS Install or Embedded Cluster installations.

This is because Helm, rather than the admin console, manages the lifecycle of the application when users install with the helm CLI. For example, instead of including an Upgrade button, the admin console delivered by the admin-console Helm chart provides the correct helm upgrade commands for users.

Add the admin-console Chart

This procedure shows how to add the admin-console Helm chart as a conditional dependency of your Helm chart.

It also shows how to exclude the admin-console Helm chart when your users install with either the KOTS Install or Embedded Cluster installation methods. It is important to exclude the admin-console chart in this scenario because both the kots CLI and the Kubernetes installer already install the admin console by default.

To conditionally include and exclude the admin-console Helm chart:

In the Helm chart Chart.yaml file, add the admin-console Helm chart to the dependencies field:

 dependencies:
 - name: admin-console
   version: "1.83.0"
   repository: "oci://registry.replicated.com/library"
   condition: admin-console.enabled

The following table describes the fields:

Field	Description
`name`	The name of the `admin-console` Helm chart.
`version`	The version of the admin console to deliver with your application. Replicated recommends that you use the latest version. For more information about the available versions, see the App Manager Release Notes.
`repository`	The URL for the Replicated private image registry where the `admin-console` Helm chart is accessed.
`condition`	A conditional statement that defines when the `admin-console` chart is included. In the next step of this procedure, you create an `admin-console` field in the `values.yaml` file of your Helm chart that maps to this conditional statement.

In the values.yaml file, add the following fields that map to the condition field in the Chart.yaml file:
```
admin-console:
 enabled: true
```
Helm Install installations read this true value from the values.yaml file and include the admin-console Helm chart in the deployment.
Package your Helm chart, and add the packaged chart to a release in the Replicated vendor portal. For more information, see Creating Releases with Helm Charts.
In the release, create or open the HelmChart custom resource manifest file. A HelmChart custom resource manifest file has kind: HelmChart and apiVersion: kots.io/v1beta1. For more information, see HelmChart in the References section.
Template:
```
apiVersion: kots.io/v1beta1
kind: HelmChart
metadata:
  name: samplechart
spec:
  ...
```
Edit the HelmChart manifest file to exclude the admin-console Helm chart during KOTS Install and Embedded Cluster installations:
1. Add the following to the values field:
```
values:
  admin-console:
   enabled: false
```
  KOTS Install and Embedded Cluster installations read this static value of false from the HelmChart custom resource, which prevents the admin-console Helm chart from deploying. Helm Install installations ignore this static value, and instead read the value of true from the values.yaml file that you added in a previous step.
  Example:
```
apiVersion: kots.io/v1beta1
kind: HelmChart
metadata:
  name: samplechart
spec:
  chart:
    name: samplechart
    chartVersion: 3.1.7
    releaseName: samplechart-release-v1
  values:
    admin-console:
     enabled: false  
```
2. If the HelmChart custom resource includes an optionalValues field, set recursiveMerge to true. This prevents the admin-console field in values from being overwritten by the fields in optionalValues.
  Example:
```
optionalValues:
 - when: "repl{{ ConfigOptionEquals `example_config_option`}}"
   recursiveMerge: true
   values:
     example_key: example_value
```
  For more information, see recursiveMerge in HelmChart.
3. Add the following to the builder field:
```
builder:
  admin-console:
    enabled: false
```
  Values in the builder field provide a way to render the chart with all images and manifests. A common use case for the builder field in Replicated is to create packages for delivering an application to an air gap environment.
  For more information, see builder in HelmChart.
  Example:
```
apiVersion: kots.io/v1beta1
kind: HelmChart
metadata:
  name: samplechart
spec:
  chart:
    name: samplechart
    chartVersion: 3.1.7
    releaseName: samplechart-release-v1
  values:
    admin-console:
     enabled: false
  builder:
    admin-console:
     enabled: false              
```
Save and promote the release to a development environment to test your changes.

Example: Delivering Custom License Fields

values.yaml

numSeats: repl{{ LicenseFieldValue "num_seats"}}

templates/deployment.yaml

        ...
        env:
          - name: NUM_SEATS
            value: {{ .Values.numSeats }}

Supporting helm CLI Installations (Beta)

Prerequisites​

About Supporting helm CLI installations​

About Installing with the helm CLI​

Overview​

Chart Versioning​

Limitations​

Delivering the Admin Console with your Application​

Overview of Delivering the Admin Console​

Add the admin-console Chart​

Example: Delivering Custom License Fields​