Working With OCI Helm Charts

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:

Unified Command Syntax: You use familiar commands, similar to those used with your favorite container runtime docker or podman. The core command structure remains consistent; helm registry login/push/pull ...
Simplified Workflow: Managing Helm Chart repositories is simpler. The need for separate helm repo add and helm repo update commands at all.
Streamlined Publishing: Publishing Helm Charts no longer requires extra plugins like the cm-push plugin that were necessary for ChartMuseum. The standard helm CLI directly supports pushing to OCI registries.
Improved Performance for Large Repositories: OCI registries are generally designed for handling large numbers of artifacts efficiently, leading to better performance.

This guide assumes that you are familiar with ChartMuseum and Helm Charts.

Logging Into to Your Registry

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 OCI based Helm Charts

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

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

Comparing ChartMuseum and OCI Helm 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.

Additional Recommendations for OCI Helm Chart Users

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.

goharbor/chartmuseum-migration-tools

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.

Helm Chart OCI Proxy