Historically, Helm Charts were often stored and distributed using dedicated chart repositories like ChartMuseum. However, modern container registries are now capable of storing various types of artifacts, including Helm Charts, using the OCI (Open Container Initiative) standard.
This shift towards OCI registries offers several advantages for managing Helm Charts, and many platforms, including Harbor, have transitioned to exclusively supporting OCI registry interfaces for Helm Charts.
Interacting with Helm Charts stored in OCI registries introduces changes compared to the traditional ChartMuseum approach, but it brings significant benefits:
docker or podman.
The core command structure remains consistent; helm registry login/push/pull ...helm repo add and helm repo update commands at all.cm-push plugin that were necessary for ChartMuseum. The standard helm CLI directly supports pushing to OCI registries.This guide assumes that you are familiar with ChartMuseum and Helm Charts.
To interact with Helm Charts in a private OCI registry
(whether to install, push, or pull them), you must first authenticate with the registry.
This is similar to logging into a container registry to manage container images.
For quick local testing, you can use your username and password or in the case of OIDC the CLI secret, for production and CI/CD environments; we strongly recommended the use of robot account.
Using Username and Password to log in into your registry:
echo $PWD | helm registry login your-subdomain.container-registry.com -u USER_NAME --stdin
Installing Helm Charts stored in OCI registries is simplified compared to
working with Chart Museum repositories. The overhead of adding and updating
repositories repo add and repo update is not needed anymore.
helm install oci://your-subdomain.container-registry.com/library/nginx --version 1.2.3
As you can see, the workflow is straightforward. All the other installation
command arguments stay the same, except that you now directly address the Chart
location in the URI format with the oci:// prefix protocol.
The option to pull the Helm Chart tarball from a specific repository is also available in case you peek into the Helm Chart templates before installing them.
# Download the Helm Chart tarball.
helm pull oci://your-subdomain.container-registry.com/library/nginx --version 1.2.3
Publishing Helm Charts to OCI registries is also simplified as not external
dependencies need to be installed cm-push plugin.
helm chart package . # . the current directory contains the Chart.yaml.
helm push ./nginx-1.2.3.tgz oci://your-subdomain.container-registry.com/library
Adapting or switching from ChartMuseum to OCI based Helm Charts does not come with much effort. The commands are similar and there are fewer steps needed to install charts
Summary Table
| Command | ChartMuseum Specific | OCI Registry Specific | Common | Notes |
|---|---|---|---|---|
helm repo add | ✅ | ❌ | Adds a ChartMuseum repo to your Helm setup. Not used with OCI. | |
helm repo update | ✅ | ❌ | Updates local cache of ChartMuseum charts. Not used with OCI. | |
cm-push (plugin) | ✅ | ❌ | Pushes chart to ChartMuseum (non-standard Helm). Not used with OCI. | |
helm registry login | ❌ | ✅ | Used for OCI authentication. | |
helm install oci://... | ❌ | ✅ | Installs directly from an OCI registry. | |
helm pull oci://... | ❌ | ✅ | Downloads chart tarball from an OCI registry. | |
helm push ... oci://... | ❌ | ✅ | Pushes a chart to an OCI registry. | |
helm install | ✅ | Generic chart installation, syntax changes slightly with OCI. | ||
helm package | ✅ | Packages a Helm chart. | ||
helm uninstall | ✅ | Uninstalls a Helm chart release. | ||
helm upgrade | ✅ | Upgrades a Helm chart release. | ||
helm get values | ✅ | Fetches the values of a release. | ||
helm template | ✅ | Renders the chart templates locally. |
This breakdown should clarify which commands are specific to each approach and where you’ll see the changes when moving from ChartMuseum to OCI-based Helm charts. The key takeaway is that OCI replaces the explicit repository management commands with direct registry interaction.
Migration from ChartMuseum to OCI based Helm Charts can be done without much effort and even adds some advantages. We recommend using OCI based Helm Charts for new projects and migrating existing projects to OCI based Helm Charts.
To ease the migration, there are a few tools available.
docker run -ti --rm 8gears.container-registry.com/library/chartmuseum2oci --url $HARBOR_URL --username $HARBOR_USER --password $HARBOR_PASSWORD
In cases when you depend on third-party Helm Chart that are ChartMuseum based, you can transparently proxy those Charts as OCI artifacts using the Helm Chart OCI Proxy.