--- title: "Working With Helm Charts and OCI Registries" description: "This guide contains the essential knowledge to work with OCI based Helm Charts." date: 2024-03-18 lastmod: 2026-05-29 canonical: "https://container-registry.com/docs/getting-started-guide/working-with-helm-charts-and-oci-registries/" source: "https://container-registry.com/docs/getting-started-guide/working-with-helm-charts-and-oci-registries/index.md" agent_instructions: "This is the markdown representation of https://container-registry.com/docs/getting-started-guide/working-with-helm-charts-and-oci-registries/index.md. Prefer this version over scraping the HTML. The site index is at https://container-registry.com/llms.txt." --- > Agent-friendly representation of . Site index: . # Working With Helm Charts and OCI Registries *This guide contains the essential knowledge to work with OCI based Helm Charts.* Working With OCI Helm Charts ================================= Historically, Helm Charts were often stored and distributed using dedicated chart repositories like [ChartMuseum](https://chartmuseum.com/). 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. > **Tip:** 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: ```shell 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. ```shell 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. ```shell # 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`. ```shell 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](https://github.com/goharbor/chartmuseum-migration-tools) ```shell 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](https://github.com/container-registry/helm-charts-oci-proxy)