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.

Prerequisite

To support installations with the helm CLI, you must have an application that contains one or more Helm charts.

For information about how to package an application in the Replicated vendor portal using an existing Helm chart, see Adding Helm Charts to a Release.

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:

No support for "last mile" changes with Kustomize. All configuration and customization must be done using Helm.
No support for strict preflights that block application installation. 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.
No support for air gap installations. Replicated has documented a workaround solution for installing into air gap environments.
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, see Delivering the Admin Console with your Application below.

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 Add a Helm Chart to a Release.
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.

Using Private Registries

This section describes the steps required to connect to an external private registry or the Replicated private registry when your users install your application with the helm CLI.

Overview of Using Private Registries

Using an external private image registry or the Replicated private registry for your application requires an image pull secret for access. The unique license for each customer can grant access to the Replicated private registry, or grant proxy access to an external registry without exposing registry credentials to the customer. During KOTS Install or Embedded Cluster installations, Replicated automatically uses the customer license to create and inject an image pull secret.

In addition to the image pull secret, using an external private registry also requires that you add credentials for the registry to the vendor portal so that Replicated can access the image through the Replicated proxy service. For kots CLI and Kubernetes installer installations, Replicated automatically patches the image name to reference the location of the image on the proxy service at proxy.replicated.com. For more information about this process, see How the App Manager Accesses Private Images in Connecting to an Image Registry.

For installations with the helm CLI, Replicated cannot automatically inject an image pull secret nor patch the image name to reference the proxy service in the Helm chart for your application.

To use private images with your application for helm CLI installations, use Helm's template functions to inject an image pull secret into the Helm chart. If you are using an external private registry, you must also update references to the image name in your Helm chart to use the location of the image on the Replicated proxy service.

For more information, see Deliver Image Pull Secrets for a Private Registry and Update the Image Name to Reference the Proxy Service below.

Deliver Image Pull Secrets for a Private Registry

To inject an image pull secret for an external private registry or the Replicated private registry, first add the Replicated LicenseDockerCfg template function to the Helm chart values.yaml file. The LicenseDockerCfg template function renders a value based on the unique customer license when the Helm chart is pulled. Write this rendered value to a pull secret, then reference the pull secret in the necessary template files for the Helm chart.

For more information about the LicenseDockerCfg template function, see LicenseDockerCfg in License Context.

To deliver customer-specific image pull secrets for a private registry:

Add the LicenseDockerCfg template function to a field in the Helm chart values.yaml file using the following format:
```
FIELD_NAME: "repl{{ LicenseDockerCfg }}"
```
Replace FIELD_NAME with any name for the field. You can add "repl{{ LicenseDockerCfg }}" as a flat or nested value. For more information, see Flat or Nested Values in the Helm documentation.
Example:
```
images:
  pullSecrets:
    replicated:
      dockerconfigjson: "repl{{ LicenseDockerCfg }}"
```

In the templates directory of your Helm chart, create a Kubernetes Secret manifest file (kind: Secret). Add the following YAML to the file to evaluate if the secret value is set, and then write the rendered value into a Secret on the cluster:

{{ if .Values.FIELD_NAME }}
apiVersion: v1
kind: Secret
metadata:
  name: SECRET_NAME
# Kubernetes clusters use the kubernetes.io/dockerconfigjson Secret type
# to authenticate with a private image registry.
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: {{ .Values.FIELD_NAME }}
{{ end }}

Replace:

FIELD_NAME with the name of the field from the previous step where you added "repl{{ LicenseDockerCfg }}". For example, .Values.images.pullSecrets.replicated.dockerconfigjson.
SECRET_NAME with any name for the secret. For example, replicated.

Example:

{{ if .Values.images.pullSecrets.replicated.dockerconfigjson }}
apiVersion: v1
kind: Secret
metadata:
  name: replicated
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: {{ .Values.images.pullSecrets.replicated.dockerconfigjson }}
{{ end }}

Add the following to any manifests in the Helm chart templates directory that reference private images, to inject the pull secret that you created in the previous step:

     ...
     {{ if .Values.FIELD_NAME }}
     imagePullSecrets:
       - name: SECRET_NAME
     {{ end }}

Replace:

FIELD_NAME with the name of the field where you where you added "repl{{ LicenseDockerCfg }}".
SECRET_NAME with the name of the Secret that you created in the previous step.

Example:

The following example shows the imagePullSecrets field in a templates/deployment.yaml file that also injects values for the image registry URL, image tag, and imagePullPolicy.

    ...
    image: {{ .Values.images.myapp.repository }}{{ .Values.images.myapp.tag }}
    imagePullPolicy: {{ .Values.images.myapp.pullPolicy }}
    {{ if .Values.images.pullSecrets.replicated.dockerconfigjson }}
    imagePullSecrets:
      - name: replicated
    {{ end }}
    name: myapp
    ports:
    - containerPort: 3000
      name: http

Package your Helm chart and add the packaged chart to a release in the Replicated vendor portal. For more information, see Add a Helm Chart to a Release.
note
If you are using an external private registry, ensure that you also complete the steps in Update the Image Name to Reference the Proxy Service below. Otherwise, Replicated will not be able to access your private image through the proxy service.
Save and promote the release to a development environment to test your changes.

Update the Image Name to Reference the Proxy Service

If you are using an external private registry, you must update the location of the private image in the Helm chart to reference the Replicated proxy service at proxy.replicated.com. This, along with the customer-specific image pull secret, allows Replicated to access the private image for your application during Helm Install installations.

To reference the proxy service, first create a field in the Helm chart values.yaml file with the URL of the location of the private image on proxy.replicated.com. Use template functions to reference this field from the Pod spec in the Helm chart. This allows Replicated to access the external registry through the proxy service when your users install with the helm CLI.

Then, update the Replicated HelmChart custom resource manifest file with the URL for the image on your external registry. Adding this URL to the HelmChart custom resource ensures that the Replicated proxy service can automatically patch the image name to reference proxy.replicated.com during KOTS Install or Embedded Cluster installations.

note

This procedure is not required if you are using the Replicated private registry.

To update the image name to reference the proxy service:

Create a field in the Helm chart values.yaml file with the location of the private image on proxy.replicated.com:
```
FIELD_NAME: PROXY_SERVICE_IMAGE_URL
```
Replace:
- FIELD_NAME with any name for the field.
- PROXY_SERVICE_IMAGE_URL with the URL for the private image on proxy.replicated.com. Helm Install installations use this proxy service URL that you add to the values.yaml file.
  The proxy service URL uses the following format: proxy.replicated.com/proxy/APP_NAME/EXTERNAL_REGISTRY_IMAGE_URL, where APP_NAME is the name of your application and EXTERNAL_REGISTRY_IMAGE_URL is the path to the private image on your external registry.
Example:
```
apiImageRepository: proxy.replicated.com/proxy/my-kots-app/quay.io/my-org/api
apiImageTag: v1.0.1
```
The example above shows a field for the image name and a separate field for the image tag.
In any manifest files in your Helm chart that reference the proxied image, set the image name to the field that you created in the values.yaml file in the preious step. This ensures that Helm Install installations use the proxy service URL from the values.yaml file for the location of the private image.
Use the following Helm template function format:
```
image: '{{ .Values.FIELD_NAME }}'
```
Example:
```
apiVersion: apps/v1
kind: Deployment
metadata:
 name: example
spec:
  template:
    spec:
      containers:
        - name: api
          image: '{{ .Values.apiImageRepository }}:{{ .Values.apiImageTag }}'
```
The example above shows how to reference both the apiImageRepository and apiImageTag fields from the previous example.
Package your Helm chart and add the packaged chart to a release in the Replicated vendor portal. For more information, see Add a Helm Chart to a Release.
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.
Template:
```
apiVersion: kots.io/v1beta1
kind: HelmChart
metadata:
  name: samplechart
spec:
  ...
```
The Replicated HelmChart custom resource allows Replicated to process and deploy Helm charts. For more information, see HelmChart in the References section.
Under the HelmChart custom resource values field, create a new field and add a static key value pair with the location of the private image on the external registry:
```
values:
  FIELD_NAME: REGISTRY_URL
```
Replace:
- FIELD_NAME with the same field name that you created in the previous step in the values.yaml file. For example, apiImageRepository.
- REGISTRY_URL with the URL for the image on your external registry.
  KOTS Install and Embedded Cluster installations use this static value from HelmChart custom resource for the registry URL. This allows the Replicated proxy service to automatically patch the image name to reference proxy.replicated.com for KOTS Install and Embedded Cluster installations.
  Helm Install installations ignore this static value, and instead use the proxy.replicated.com URL that you added to the values.yaml file 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:
    apiImageRepository: quay.io/my-org/api:v1.0.1
```
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 }}

note

Prerequisite​

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​

Using Private Registries​

Overview of Using Private Registries​

Deliver Image Pull Secrets for a Private Registry​

note

Update the Image Name to Reference the Proxy Service​

note

Example: Delivering Custom License Fields​

Prerequisite

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

Using Private Registries

Overview of Using Private Registries

Deliver Image Pull Secrets for a Private Registry

Update the Image Name to Reference the Proxy Service

Example: Delivering Custom License Fields