Creating Releases with Helm Charts

This topic describes how to add a Helm chart to a release in the Replicated vendor portal or the replicated CLI. Adding a Helm chart to a release is useful if you want to distribute a Kubernetes application with Replicated that is already packaged using Helm.

This procedure applies for Replicated Helm installations and native Helm installations. For more information, see Helm Overview.

About Releasing with Helm Charts

You can add one or more Helm charts to a release in the vendor portal by uploading each Helm chart as a .tgz package. This allows you to use Replicated to distribute applications that are packaged with Helm.

When you add a Helm chart to a release, Replicated adds a copy of the Chart.yaml file and the values.yaml file from the Helm chart to the release.

You must also have a HelmChart custom resource manifest file in the release for each Helm chart that you add. You use this HelmChart custom resource to configure the Helm chart with your application.

The following table provides more information about these files:

File	Description
HelmChart custom resource	A HelmChart custom resource is a YAML file with `kind: HelmChart`. When you drag and drop a Helm chart `.tgz` to a release in the vendor portal, Replicated automatically creates a corresponding HelmChart custom resource manifest that uses the naming convention `CHART_NAME.yaml`. For example, `postgresql.yaml`. The HelmChart custom resource references the `.tgz` export of the Helm chart and provides the necessary instructions to the Replicated app manager for processing and preparing the chart for deployment. For more information, see HelmChart in the Custom Resources section.
Chart.yaml	Replicated extracts the `Chart.yaml` file from the Helm chart `.tgz` file that you provide. This file is read-only and cannot be edited in the release.
values.yaml	Replicated extracts the `values.yaml` file from the Helm chart `.tgz` file that you provide. This file is read-only and cannot be edited in the release.

For example, the following screenshot shows how a Postgres Helm chart displays in the file tree of a release in the vendor portal:

Postgres Helm Chart

Package a Helm Chart

To include a Helm chart in a release, first package the Helm chart, including any of its dependencies, as a .tgz file. Then, add the .tgz Helm chart package to your release.

There are different steps for creating the Helm chart package depending on if the Helm chart source is in a remote chart repository such as Artifact Hub, or in a local directory.

For more information about the Helm CLI commands in this procedure, see the Helm Commands section in the Helm documentation.

To package a Helm chart and add it to a release:

If the Helm chart source is in a chart repository, do the following:
1. Update your local directory with the latest available Helm chart information from your chart repositories. Run:
```
helm repo update
```
  note
  You can also pass the names of a specific repository or repositories that you want to update in the helm repo update command. For more information, see Helm Repo Update in the Helm documentation.
2. Download the latest copy of the desired Helm chart from a repository. Run:
```
helm fetch REPO_NAME/CHART_NAME
```
  Replace:
  - REPO_NAME with the name of the repository where the Helm chart is located.
  - CHART_NAME with the name of the Helm chart as it appears in the repository.
  The Helm chart, including any dependencies, is packaged and copied to your current directory in a .tgz file. The file uses the naming convention: CHART_NAME-VERSION.tgz. For example, postgresql-8.1.2.tgz.
If the Helm chart source is in your local directory, do the following:
1. In your local directory, cd to the location of the Chart.yaml file for the Helm chart.
2. If the Chart.yaml file includes any dependencies, update the charts/ directory. Run:
```
helm dependency update
```
3. Package the Helm chart. Run:
```
helm package .
```
  The Helm chart, including any dependencies, is packaged and copied to your current directory in a .tgz file. The file uses the naming convention: CHART_NAME-VERSION.tgz. For example, postgresql-8.1.2.tgz.

Next, create and promote a release using one of the following methods:

Using the Vendor Portal
Using the CLI

Using the Vendor Portal

When you create a release in the vendor portal, Replicated automatically creates the HelmChart custom resource manifest file for the Helm chart when you drag and drop your Helm chart .tgz file from your local directory to the file tree in the vendor portal.

To create and promote a release in the vendor portal:

From the Applications dropdown list, select Create an app or select an existing application to update.
Click Releases on the left menu, and click Create release.
View a larger image
For the first release of an application, drag and drop your application files into the file directory in the YAML editor.
If you are editing a draft or an existing non-promoted release, the files appear in the YAML editor. You can drag and drop new manifest files as needed.
You can also click the plus icon to add a new, untitled YAML file.
Edit the YAML files as needed, and click Save release. This saves a draft that you can continue to edit until you promote it.
note
To edit a draft release, click Edit YAML from the Releases page.

Click Promote. In the Promote Release dialog that opens, edit the fields:

Field	Description
Channel	Select the channel where you want to promote the release. The defaults are Stable, Beta, and Unstable. If you created custom channels, they are listed here also.
Version label	Enter a version label. If semantic versioning is enabled for the channel, you must use a valid semantic version using the X.Y.Z format, where X is the major version, Y is the minor version, and Z is the patch version. These must be non-negative integers and cannot contain leading zeroes. Each element must increase numerically. For more information, see Enable Semantic Versioning in About Releases and Semantic Versioning on the Semantic Versioning website.
Requirements	Select Prevent this release from being skipped during upgrades to mark the release as required. When a release is required, the admin console requires users to upgrade to that version before they can upgrade to a later version. For example, if you select Prevent this release from being skipped during upgrades for release v2.0.0, users with v1.0.0 deployed must upgrade to v2.0.0 before they can upgrade to a version later than v2.0.0, such as v2.1.0. Required releases are supported in the app manager v1.68.0 and later. After users deploy a required version, they can no longer redeploy (roll back to) versions earlier than the required version, even if `allowRollback` is `true` in the Application custom resource manifest. See allowRollback in the Application custom resource topic.
Release notes	Add detailed release notes. The release notes support markdown and are shown to your customer.

Click Promote.
The release appears in an Active state on the Releases page.

Using the CLI

Prerequisites

Before you can create your first release with Replicated, make sure that the following requirements are met:

Configure the environment variables and install the replicated CLI. See Installing the replicated CLI.
note
Exporting the token environment variable is valid for a single session. You must export it for each new session.
Create a new application using the replicated app create APP_NAME command. You only need to do this procedure once for each application that you want to deploy. See app create in Reference.

Create and Promote a Release

This procedure shows how to create a new release using local application files and the replicated CLI.

To create and promote a new release:

Copy the Helm chart .tgz package to the local directory that contains the manifest files for the release.
Create a HelmChart custom resource manifest file in the same directory where you copied the .tgz file. Name the HelmChart manifest file CHART_NAME.yaml. For example, postgresql.yaml.

Copy and paste the following YAML into the HelmChart manifest:

apiVersion: kots.io/v1beta1
kind: HelmChart
metadata:
   # name matches the file name that you used.
   # If you saved the file as CHART_NAME.yaml, use name: CHART_NAME
   name: CHART_NAME
spec:
# chart identifies the Helm chart from the .tgz
# Replace CHART_NAME with the name of the chart from the .tgz
# Replace CHART_VERSION with the version of the chart from the .tgz
   chart:
      name: CHART_NAME
      chartVersion: CHART_VERSION

   # helmVersion identifies the version of Helm used to render the chart.
   # Possible values are v2 or v3.
   helmVersion: v3

   # useHelmInstall identifies whether this Helm chart uses the
   # Replicated Helm installation (false) or native Helm installation (true).
   # Native Helm installation is available for Helm v3 charts only.
    useHelmInstall: true

   # values maps user-provided values with the Helm chart values.yaml file.
   # You can leave the values attribute empty for this procedure.
   values: {}

   # builder values are used to create air gap packages.
   # You can leave the builder attribute empty for this procedure.
   builder: {}

For more information, see HelmChart in the Custom Resources section.

Lint the manifest files and ensure that there are no errors in the YAML:
```
replicated release lint --yaml-dir=PATH_TO_APP_DIR
```
Replace PATH_TO_APP_DIR with path to the directory of the YAML manifest files.
For more information about linting, see release lint and Linter Rules in Reference.
Create a new release:
```
replicated release create --yaml-dir PATH_TO_APP_DIR
```
Replace PATH_TO_APP_DIR with the path to the directory of the YAML manifest files.
For more information, see release create or release update in Reference.
Continue to edit and lint the release as needed, then update the release:
```
replicated release update SEQUENCE --yaml-dir PATH-TO-APP-DIRECTORY
```
Replace:
- SEQUENCE with the release sequence number. This identifies the existing release to be updated.
- PATH_TO_APP_DIR with the path to the directory of the YAML manifest files.
For more information, see release update in Reference.
Promote the release when you are ready to test it. Releases cannot be edited after they are promoted. To make changes after promotion, you have to create a new release.
```
replicated release promote SEQUENCE CHANNEL_ID
```
Replace:
- SEQUENCE with the release sequence number.
- CHANNEL_ID with the channel ID or case sensitive name of the channel.
For more information, see release promote in the replicated CLI documentation.
Verify that the release was promoted to the channel:
```
replicated release ls
```

Next Steps

The following are the recommended next steps to test the application in your development environment:

To add a customer, see Creating a Customer.
If you are installing for the first time, see Overview of Installing an Application with the App Manager in the Enterprise section.
If you are updating an existing installation, see Updating an Application in the Enterprise section.

About Releasing with Helm Charts​

Package a Helm Chart​

note

Using the Vendor Portal​

note

Using the CLI​

Prerequisites​

note

Create and Promote a Release​

Next Steps​

About Releasing with Helm Charts

Package a Helm Chart

Using the Vendor Portal

Using the CLI

Prerequisites

Create and Promote a Release

Next Steps