Installing with Helm
This topic describes how to use Helm to install releases that contain one or more Helm charts. For more information about the
helm install command, including how to override values in a chart during installation, see Helm Install in the Helm documentation.
The following diagram shows how Helm charts distributed with Replicated are installed with Helm in customer environments:
As shown in the diagram above, when a release containing one or more Helm charts is promoted to a channel, the Replicated vendor portal automatically extracts any Helm charts included in the release. These charts are pushed as OCI objects to the Replicated registry. The Replicated registry is a private OCI registry hosted by Replicated at
registry.replicated.com. For information about security for the Replicated registry, see Replicated Registry Security.
For example, if your application in the vendor portal is named My App and you promote a release containing a Helm chart with
name: my-chart to a channel with the slug
beta, then the vendor portal pushes the chart to the following location:
Customers can install your Helm chart by first logging in to the Replicated registry with their unique license ID. This step ensures that any customer who installs your chart from the registry has a valid, unexpired license. After the customer logs in to the Replicated registry, they can run
helm install to install the chart from the registry.
Replicated Helm Values
When a customer installs your Helm chart from the Replicated registry, the Replicated registry injects values into the
global.replicated field of the Helm chart values file.
The following is an example of a Helm values file containing the
global.replicated field injected by the Replicated registry:
# Helm values.yaml
customerEmail: [email protected]
customerName: Example Customer
description: License Expiration
The values in the
global.replicated field provide information about the following:
- Details about the fields in the customer's license, such as the field name, description, signature, value, and any custom license fields that you define. You can use this license information to check license entitlments before the application is installed. For more information, see Check Entitlements Before Installation in Checking Entitlements for Helm Installations.
- A base64 encoded Docker configuration file. To proxy images from an external private registry with the Replicated proxy service, you can use the
global.replicated.dockerconfigjsonfield to create an image pull secret for the proxy service. For more information, see Proxying Images for Helm Installations.
Helm CLI installations do not provide access to any of the features of the Replicated KOTS installer, such as:
- Air gap bundles for installations into air gapped environments
- The Replicated admin console
- Strict preflight checks that block installation
- Backup and restore with snapshots
- Required releases with the Prevent this release from being skipped during upgrades option
Before you install, complete the following prerequisites:
- You must have a customer in the Replicated vendor portal with a valid email address. This email address is only used as a username for the Replicated registry and is never contacted. For more information about creating and editing customers in the vendor portal, see Creating a Customer.
- (Recommended) To install the Replicated SDK alongside the application, declare the SDK as a dependency. For more information, see Install the SDK as a Subchart in Installing the Replicated SDK.
To install a Helm chart:
In the vendor portal, go to Customers and click on the target customer.
Click Helm install instructions.
In the Helm install instructions dialog, run the first command to log in to the Replicated registry:
helm registry login registry.replicated.com --username EMAIL_ADDRESS --password LICENSE_ID
EMAIL_ADDRESSis the customer's email address
LICENSE_IDis the ID of the customer's license
You can safely ignore the following warning message:
WARNING: Using --password via the CLI is insecure.This message is displayed because using the
--passwordflag stores the password in bash history. This login method is not insecure.
Alternatively, to avoid the warning message, you can click (show advanced) in the Helm install instructions dialog to display a login command that excludes the
--passwordflag. With the advanced login command, you are prompted for the password after running the command.
(Optional) Run the second and third commands to install the preflight plugin and run preflight checks. If no preflight checks are defined, these commands are not displayed. For more information about defining and running preflight checks, see About Preflight Checks and Support Bundles.
Run the fourth command to install using Helm:
helm install RELEASE_NAME oci://registry.replicated.com/APP_SLUG/CHANNEL/CHART_NAME
RELEASE_NAMEis the name of the Helm release.
APP_SLUGis the slug for the application. For information about how to find the application slug, see Get the Application Slug.
CHANNELis the lowercased name of the channel where the release was promoted, such as
unstable. Channel is not required for releases promoted to the Stable channel.
CHART_NAMEis the name of the Helm chart.
To install the SDK with custom RBAC permissions, include the
--setflag with the
helm installcommand to override the value of the
replicated.serviceAccountNamefield with a custom service account. For more information, see Customizing RBAC for the SDK.
(Optional) In the vendor portal, click Customers. You can see that the customer you used to install is marked as Active and the details about the application instance are listed under the customer name.