Skip to main content

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.

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 file. This allows you to use Replicated to distribute applications that are packaged in part or in whole with Helm. The procedures in this topic apply to native Helm installations (recommended) and Replicated Helm installations. For more information, see About Deploying with Helm.

When you add a Helm chart to a release, Replicated displays 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 for each Helm chart that you add to a release. By default, Replicated adds the HelmChart custom resource if you are using the vendor portal, which you use to configure how the app manager deploys the chart. If you are using the CLI, you must add the HelmChart custom resource manually.

The following table provides more information about these files:

FileDescription
HelmChart custom resourceA 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.yamlReplicated 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.yamlReplicated 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

View a larger image

About Updating Replicated Helm Releases​

useHelmInstall is a chart-level flag that is set to true to specify the use of native Helm. Native Helm can only be set for new charts. Modifying this flag in existing charts for existing applications is not supported because charts installed with Replicated Helm cannot be migrated to native Helm.

However, you can add native Helm charts to an existing release that already uses Replicated Helm. Each chart is installed using the specified installation method for that chart, indicated by the value of the useHelmInstall flag.

Create the Helm Chart Package​

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:

  1. 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.

  2. 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.

Add the Helm Chart to a Release​

After you create the Helm chart .tgz package, you can create and promote a release with the Helm chart package using one of the following methods:

Using the Vendor Portal​

To create and promote a release in the vendor portal:

  1. From the Applications dropdown list, select Create an app or select an existing application to update.

  2. Click Releases on the left menu, and click Create release.

    Create Release

    View a larger image

  3. Drag and drop the Helm chart .tgz package that you created as part of Create the Helm Chart Package into the file directory in the YAML editor.

  4. In the Select Helm Install Method dialog that displays, select the method that the app manager uses to install the Helm chart. Replicated recommends that you select the Native Helm installation method. The Replicated Helm method is listed as Replicated KOTS.

    Select helm install method dialog

    For more information about the limitations of each method, see Native Helm and Replicated Helm Limitations.

    After you select the installation method, the vendor portal automatically creates a HelmChart custom resource manifest file for the Helm chart in the release. For information about the HelmChart custom resource, see HelmChart in Reference.

  5. Edit the files in the release as needed. You can also:

    note

    You can drag and drop additional application manifest files or click the plus icon to add new, untitled files.

  6. 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.

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

    FieldDescription
    ChannelSelect 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 notesAdd detailed release notes. The release notes support markdown and are shown to your customer.

  8. Click Promote.

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

Using the CLI​

This section describes the prerequisites and steps for creating and promoting a release using the replicated CLI.

Prerequisites​

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

  1. 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.

  2. 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:

  1. Copy the Helm chart .tgz package to the local directory that contains the manifest files for the release.

  2. 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.

  3. Copy and paste the following YAML into the HelmChart manifest. The useHelmInstall flag is set to true, specifying that the release uses the recommended native Helm installation. For more information, see HelmChart in the Custom Resources section.

    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: {}

  4. 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.

  5. 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.

  6. Continue to edit and lint the release as needed. You can:

  7. 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.

  8. 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.

  9. 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: