Helm Chart Repository

Helm is a package manager for Kubernetes that allows development and operations teams to easily manage and deploy these increasingly complex cloud native applications to their Kubernetes clusters. Helm allows you to manage applications on your Kubernetes cluster in much the same way as you’d manage applications on your Linux server with apt or yum.

Helm works by packaging up a set of YAML definitions along with the necessary configuration to quickly stand up all components of an application in a repeatable way. A single chart can be as simple or complex as necessary, deploying anything from a single container to a full distributed application. Helm combines these application definitions with user-provided configuration to allow simple overriding of configuration where needed, allowing users to concentrate on shipping software and not on the nitty-gritty of configuring every application they need to run.

Helm packages are known as “Charts” and are stored in a “Chart Repository”. By default, Helm comes bundled with the “stable” chart repository, hosted for free by Google. Most public charts are hosted here, mostly provided by vendors packaging their own software for use by others.

For more information on Helm, please see:

• Helm: The official website for Helm
• Helm Hub: The official public repository for Helm Charts
• Helm Documentation: Helm Documentation
• Kubernetes Documentation: Kubernetes Documentation

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy n' paste snippets (with your namespace/repo/rsa-key pre-configured).

In the following examples:

Upload a Chart

To upload, you will need to generate your chart first. You can do this with the helm CLI:

helm package .

This generates a chart package file (.tgz) like CHART_NAME-CHART_VERSION.tgz that you can upload.

📘

Please see the official Chart development guide for more information on building your own Charts for distribution.

Upload via OCI with Helm v3

🚧

OCI support is currently in Early Access. Helm Charts uploaded via OCI will show as "Docker Packages" on Cloudsmith.
Helm Charts uploaded via OCI aren't available to download via the classic Chart.yaml repository method

Starting Helm v3.8.0 OCI-compliant registries can now be used to store and share chart packages. For full detail see Helm Docs .

Setup

Before you can push your chart you need to login to Cloudsmith's registry.

helm registry login docker.cloudsmith.io -u token -p TOKEN

helm registry login docker.cloudsmith.io -u USERNAME -p PASSWORD

helm registry login docker.cloudsmith.io -u USERNAME -p API-KEY

Push your chart

The command to upload a Helm Chart via OCI using the Helm CLI is:

helm push CHART_NAME-CHART_VERSION.tgz oci://docker.cloudsmith.io/OWNER/REPOSITORY

Upload via the Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

The command to upload a Helm chart via the Cloudsmith CLI is:

cloudsmith push helm OWNER/REPOSITORY CHART_NAME-CHART_VERSION.tgz

Example:

cloudsmith push helm org/repo your-chart-1.0.0.tgz

Upload via Cloudsmith Website

Please see Upload a Package for details of how to upload via the Website UI.

Example Project

For examples of what your project should look like for packaging and publishing/uploading, please have a look at our examples repository (on GitHub). We'll supplement these with more detailed guidance later but otherwise, just ask! - we're here to help.

Download / Install a Chart

Setup for OCI-based charts

🚧

OCI support is currently in Early Access. Helm Charts uploaded via OCI will show as "Docker Packages" on Cloudsmith.
Helm Charts uploaded via OCI aren't available to download via the classic Chart.yaml repository method

Private Repositories

Assuming you have Helm v3.8.0 already installed, before you can pull a chart you need to login to Cloudsmith's registry.

helm registry login docker.cloudsmith.io -u token -p TOKEN

helm registry login docker.cloudsmith.io -u USERNAME -p PASSWORD

helm registry login docker.cloudsmith.io -u USERNAME -p API-KEY

Public Repositories

With public repositores you don't need any sort of authentication and you can jump straight to Installing a Chart

Setup for classic repository

Assuming you have helm already installed, it is straight-forward to add a Cloudsmith-based chart repository. You use the helm repo add and helm repo update commands as follows:

Public Repositories

helm repo add NAME \
  'https://dl.cloudsmith.io/public/OWNER/REPOSITORY/helm/charts/' 
helm repo update

Private Repositories

📘

Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication.

The setup method will differ depending on what authentication type you choose to use.

🚧

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs

helm repo add NAME \
  'https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/helm/charts/' 
helm repo update

helm repo add NAME \
  'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/helm/charts/'  \
  --username USERNAME \
  --password PASSWORD
helm repo update

helm repo add NAME \
  'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/helm/charts/'  \
  --username USERNAME \
  --password API-KEY
helm repo update

helm repo add NAME \
  'https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/helm/charts/'  \
  --username token \
  --password TOKEN
helm repo update

Installing a Chart

To install/use a specific version of a chart:

helm install NAME/CHART_NAME --version CHART_VERSION

helm install oci://docker.cloudsmith.io/OWNER/REPOSITORY/CHART_NAME --version CHART_VERSION

To install the latest version of a chart:

helm install NAME/CHART_NAME

helm install oci://docker.cloudsmith.io/OWNER/REPOSITORY/CHART_NAME

Or you can upgrade to the most recent version of a chart if you've already installed:

helm upgrade NAME/CHART_NAME

helm upgrade oci://docker.cloudsmith.io/OWNER/REPOSITORY/CHART_NAME

If you've got a requirements.yaml file in your chart, you can specify this as a dependency:

dependencies:
  - name: CHART_NAME
    version: CHART_VERSION
    repository: NAME

Removing Setup (Classic Repository)

Helm provides a very clean method of removing a chart repository, simply run the following command:

helm repo remove NAME

Logging out of OCI Registry

Helm provides a command to logout of OCI-based registries

helm registry logout docker.cloudsmith.io

Provenance

🚧

Provenance files aren't supported for OCI chart uploads yet, but this feature is coming soon.

Provenance files allow for verification of both the integrity and source of a Helm chart. Cloudsmith fully supports both verification and generation of Helm provenance files.

Building Provenance Files

Provenance files can be built whilst packaging helm charts, by passing in the --sign and --key switches:

helm package --sign --key "Your Key Name" .

The Helm client will prompt for the secret key used to sign your Chart. One complete, a .prov file will coexist alongside your chart tarball.

Uploading Provenance Files

Provenance files may be uploaded on the UI as above.

Upload via the Cloudsmith CLI

Provenance files can be passed to the Cloudsmith CLI during a push. Please note this requires version 2.0.4 (or later) of the cloudsmith-api Python package:

cloudsmith push helm OWNER/REPOSITORY --provenance-file CHART_NAME-CHART_VERSION.tgz.prov CHART_NAME-CHART_VERSION.tgz

Automated Generation of Provenance Files

Where a provenance file has not been provided at upload, Cloudsmith will automatically generate one during synchronization. Generated provenance files will be signed using the current repository GPG signing key.

Verifying a Chart

Charts and provenance files may verified by passing the --verify switch to helm install:

helm install --verify NAME/CHART_NAME

Note that this will require the GPG public key of the repository to be installed to the keyring of the target system.

Upstream Proxying / Caching

Configurable Proxying Caching

You can configure upstream Helm repositories that you wish to use for charts that are not available in your Cloudsmith repository. In addition, you can also choose to cache any requested charts for future use.

Please see our Upstream Proxying documentation for further instructions.

Key Signing Support

GPG Packages

Troubleshooting

Please see the Troubleshooting page for further help and information.