How to Push Your Helm Charts to a Docker (OCI) Registry

Introduction
Helm has become the go-to package manager for Kubernetes, simplifying the deployment and management of complex applications by bundling all the required Kubernetes manifests into easily distributable “charts.” Traditionally, Helm charts have been hosted in dedicated Helm repositories or stored as files in version control systems. However, with the advent of Helm 3 and its support for OCI (Open Container Initiative) specifications, you can now store and distribute Helm charts via Docker (OCI) registries—just like container images.

In this post, we’ll walk through the process of preparing your Helm chart, authenticating to a Docker registry, and using the OCI support in Helm 3 to push your chart to a Docker-based registry such as Docker Hub or a private OCI-compatible registry.

Prerequisites

1. Docker Registry Access:
   You’ll need access to a Docker registry (such as Docker Hub, Amazon ECR, or a self-hosted OCI-compatible registry) and proper permissions to push images.
   • For Docker Hub, you need a Docker Hub account.
   • For self-hosted registries, ensure you have a reachable endpoint and credentials.

OCI Support Enabled (If Needed):
For Helm versions prior to 3.8, you might need to explicitly enable the experimental OCI feature:

export HELM_EXPERIMENTAL_OCI=1

From Helm 3.8 onwards, OCI support is stable and enabled by default.

Helm 3.7 or Later:
OCI support in Helm started as an experimental feature but is now stable in Helm 3.7+. Make sure you have a recent version:

helm version

If you’re running an older version, you can download the latest release.

Step-by-Step Guide

Step 1: Prepare Your Helm Chart

If you don’t already have a Helm chart, you can create one using:

helm create mychart

This command generates a starter chart in the mychart directory. Inside, you’ll find a Chart.yaml, values.yaml, templates, and other configuration files. Adjust the chart’s metadata, deployment configurations, and values as needed for your application.

Step 2: Package the Helm Chart

Before pushing to a registry, you need to package your Helm chart into a .tgz archive. The helm package command does this easily:

cd mychart
helm package .

This command creates a file named mychart-<version>.tgz in the current directory. The version is pulled from Chart.yaml.

Step 3: Enable and Use OCI Support (If Required)

If you’re using Helm 3.7 or earlier, you must enable OCI support by setting an environment variable:

export HELM_EXPERIMENTAL_OCI=1

For Helm 3.8 and later, OCI support is automatically enabled, and you can skip this step.

Step 4: Log In to the Docker Registry

To push your Helm chart, you need to be authenticated to the registry. For Docker Hub, you can use:

helm registry login registry-1.docker.io \
  --username <your-username> \
  --password <your-password>

If you’re using another OCI-compatible registry (for example, ghcr.io for GitHub Container Registry or a private registry), adjust the URL accordingly:

helm registry login ghcr.io \
  --username <your-username> \
  --password <your-personal-access-token>

Successful login means Helm (and underlying tooling) have stored your credentials for subsequent operations.

Step 5: Push the Helm Chart to the Registry

With OCI, Helm treats the registry similarly to how you would push images. The syntax involves specifying an oci:// prefix. For example, to push your mychart-<version>.tgz chart to Docker Hub under your account myusername:

helm push mychart-<version>.tgz oci://registry-1.docker.io/myusername/helm-charts

What’s happening here?

• oci:// indicates that you’re using an OCI registry.
• registry-1.docker.io/myusername/helm-charts is the path to the repository within the Docker Hub. You can think of it like myusername/helm-charts in Docker Hub’s naming convention.

If everything is correct, Helm will push the chart and give you a confirmation message. Your chart is now stored in the Docker registry, just like a container image.

Step 6: Verify the Chart in the Registry

After pushing, you can verify that the chart exists in the registry. While Helm doesn’t have a direct “list” command for registries at this point, you can use helm pull to confirm retrieval:

helm pull oci://registry-1.docker.io/myusername/helm-charts/mychart --version <chart-version>

If the pull succeeds, you’ve confirmed that the chart was successfully stored and can be retrieved.

Additional Tips and Best Practices

1. Versioning and Tagging:
   Treat your Helm charts like container images—use semantic versions and consider appending additional tags for clarity. This makes it easier to manage, roll back, and track deployments over time.
2. Automated CI/CD Pipelines:
   Integrate chart packaging and pushing into your CI/CD pipeline. For instance, a GitHub Actions workflow can automatically package and push the chart upon merging to the main branch.
3. Use Private Registries for Proprietary Software:
   If your application and charts are not open-source or public, consider using a private OCI registry. Many cloud providers offer private container registries with native OCI support.
4. Access Control and RBAC:
   Manage access to your Helm charts using the registry’s authentication and authorization mechanisms. This ensures that only trusted team members or CI/CD agents can push or pull charts.