Skip to main content

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:

About Supporting helm CLI Installations​

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

  • KOTS Install: Install in an existing cluster using the Replicated kots CLI or the Replicated admin console
  • Embedded Cluster: Install in an embedded cluster provisioned by Replicated kURL
  • Helm Install: Install in 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 KOTS 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, KOTS 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.

About Installing with the helm CLI​

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 when your users install using the helm CLI.

Example: Delivering Custom License Fields​

values.yaml

numSeats: repl{{ LicenseFieldValue "num_seats"}}

templates/deployment.yaml

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