About Distributing Applications with Replicated
This topic describes the options for using Replicated to distribute applications, including information about supporting installations with the Helm CLI and with the Replicated KOTS installer.
About Installations with the Helm CLI
You can distribute your Helm chart-based application with Replicated and allow your customers to install with the Helm CLI. Additionally, you can add the Replicated SDK Helm chart as a subchart of your application to get access to Replicated functionality. For more information, see About Distributing the Replicated SDK with an Application below.
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 the Beta channel, then the vendor portal pushes the chart to the following location: oci://registry.replicated.com/my-app/beta/my-chart
.
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.
For more information about how to install an application with Helm, see Installing with Helm.
For information about how to get started distributing your Helm chart with Replicated, see Replicated Quick Start.
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
global:
replicated:
channelName: Stable
customerEmail: [email protected]
customerName: Example Customer
dockerconfigjson: eyJhdXRocyI6eyJd1dIRk5NbEZFVGsxd2JGUmFhWGxYWm5scloyNVRSV1pPT2pKT2NGaHhUVEpSUkU1...
licenseFields:
expires_at:
description: License Expiration
name: expires_at
signature:
v1: iZBpESXx7fpdtnbMKingYHiJH42rP8fPs0x8izy1mODckGBwVoA...
title: Expiration
value: "2023-05-30T00:00:00Z"
valueType: String
licenseID: YiIXRTjiB7R...
licenseType: dev
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.dockerconfigjson
field to create an image pull secret for the proxy service. For more information, see Proxying Images for Helm Installations.
Limitations
The following limitations apply when using Helm to install applications distributed with Replicated:
Replicated does not support Helm installations into air gap environments.
Helm installations do not provide access to any of the features of the Replicated KOTS installer, including:
- 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
About Installations with KOTS
You must have the Replicated KOTS entitlement to use the Replicated KOTS and kURL installers and features.
The Replicated KOTS installer provides highly successful installs of Kubernetes applications or Helm charts in diverse customer environments, including on-prem and air gap environments. Additionally, the Replicated kURL installer allows customers that do not have their own Kubernetes cluster to install your application with KOTS by provisioning a cluster on a virtual machine (VM) or bare metal server. For more information, see About KOTS and kURL.
KOTS provides access to feautures such as:
- Support for air gap installations
- Insights and telemetry sent to the vendor portal for instances running in online or air gap environments
- The Replicated admin console, which provides a user interface where your customers can enter their application configuration preferences, upgrade their instance, view performance metrics, and more
- Strict preflight checks that block installation if environment requirements are not met
- Backup and restore with Replicated snapshots
- Required releases with the Prevent this release from being skipped during upgrades option
In addition to the features listed above, you can distribute the Replicated SDK with your application to get access to more Replicated features, including support for collecting custom metrics from application instances. For more information, see About Distributing the Replicated SDK with an Application below.
The following diagram demonstrates how applications distributed with Replicated are installed into an existing cluster or VM with KOTS and kURL:
As shown in the diagram above, customers can install an application by first installing KOTS in their existing cluster or in the cluster provisioned by kURL. Then, they can use KOTS to configure and install the application. For more information about installing with KOTS and kURL, see About Installing an Application.
Helm Charts with KOTS
Helm is a popular package manager for Kubernetes applications. For vendors that support installations with KOTS, Replicated strongly recommends that you distribute your application as a Helm chart. When you distribute your application as a Helm chart, you can support both installations with the Helm CLI and with KOTS from the same release, without having to maintain separate sets of Helm charts or application manifests. This is important because many enterprise users expect to be able to install an application with Helm.
Also, using KOTS to distribute Helm charts provides additional functionality not directly available with the Helm CLI, such as a user interface for collecting user configuration values and backup and restore with snapshots.
For information about how to get started distributing your Helm chart with Replicated so that you can support both installations with the Helm CLI and with KOTS, see Replicated Quick Start.
For more information about how KOTS installs Helm charts, see About Distributing Helm Charts with KOTS.
About Distributing the Replicated SDK with an Application
The Replicated SDK is a Helm chart that can be installed as a small service alongside your application. The SDK can be installed alongside Helm chart- or standard manifest-based applications using the Helm CLI or KOTS.
For information about how to distribute and install the SDK with your application, see Installing the Replicated SDK.
Replicated recommends that the SDK is distributed with all applications because it provides access to key Replicated functionality, such as:
- Automatic access to insights and operational telemetry for instances running in customer environments. For more information, see About Instance and Event Data.
- An in-cluster API that you can use to embed Replicated features into your application, including:
- Collect custom metrics on instances running in online or air gap environments. See Configuring Custom Metrics.
- Check customer license entitlements at runtime. See Checking Entitlements for Helm Installations (Beta) and Verifying License Field Signatures for Helm Installations (Beta).
- Provide update checks to alert customers when new versions of your application are available for upgrade. See Support Update Checks in Your Application in Replicated SDK API (Beta).