Introduction
The article addresses performance and scalability issues with legacy Helm repositories, where metadata calculation can be slow and the index.yaml file may grow significantly in size over time. To address this, we suggest moving over to helmOCI repositories.
This article outlines how to migrate legacy Helm charts from a traditional Helm repository to the OCI format, and how to push them into an OCI-compliant Helm repository in Artifactory.
Resolution
Helm Client: 3.17 +
To convert your legacy Helm charts to an OCI-compatible repository, you’ll need to pull the existing .tgz charts from your current repo and then push them to the new OCI-based repository
1. I have repositories with legacy Helm charts served through virtual repositories. For example, the screenshot below shows two versions of the metrics-agent chart that are present in the repositories under a virtual repository as .tgz files. I’m now looking to start converting these into OCI format.
I added my helm-legacy-virtual repository to my helm client.
helm repo add alec-legacy-virtual https://<url>.jfrog.io/artifactory/api/helm/alec-legacy-virtual --username alecc@jfrog.com --password <reference-token>
2. I then pull the helm chart using the helm client:
helm pull alec-legacy-virtual/metrics-agent --version 2.12.0
❯ ls
metrics-agent-2.12.0.tgz
❯ helm pull alec-legacy-virtual/metrics-agent --version 2.11.39
❯ ls
metrics-agent-2.11.39.tgz metrics-agent-2.12.0.tgz
Please note that you can also curl to download .tgz file directly with the following command
curl -H "Authorization: Bearer <reference-token>" https://<url>.jfrog.io/artifactory/alec-legacy-virtual/metrics-agent-2.11.39/metrics-agent-2.11.39.tgz
3. Now I am going to push to my "helmOCI" repo.
4. Access Method Configuration
Helm OCI repositories use the Docker access method configured in your Artifactory instance. On my test server, I’m using the subdomain method, where the repository name is part of the domain—for example:
oci://<url>-alec-helmoci-local.jfrog.io.
If your environment is set up with the repository path method, the URL structure will look like:
oci://<url>.jfrog.io/alec-helmoci-local.
You can verify which access method your instance uses by checking the commands provided under the Set Me Up section in the Artifactory UI.
❯ helm push metrics-agent-2.12.0.tgz \
oci://<url>-alec-helmoci-local.jfrog.io
Pushed: <url>-alec-helmoci-local.jfrog.io/metrics-agent:2.12.0
Digest: sha256:ae5fbee445344a61b0486665ce6344d98a3c9f302435a923ab352227881d00b7
❯helm push metrics-agent-2.11.39.tgz \
oci://<url>-alec-helmoci-local.jfrog.io
Pushed: <url>-alec-helmoci-local.jfrog.io/metrics-agent:2.11.39
Digest: sha256:25bd0351abd9dcdfd96a86d5a1b05cecc8893d402610c2d3acb53a5883920eb5
##expected repository path version of the command
❯helm push metrics-agent-2.11.39.tgz \
oci://<url>.jfrog.io/alec-helmoci-local
5. Then afterwards we see the helm chart saved in the helmOCI repo. The operation is simply retagging the image with OCI.
6. Then afterwards, we are able to successfully pull from helmOCi repo:
❯ helm pull oci://<url>-alec-helmoci-local.jfrog.io/metrics-agent
Pulled: <url>-alec-helmoci-local.jfrog.io/metrics-agent:2.12.0
Digest: sha256:ae5fbee445344a61b0486665ce6344d98a3c9f302435a923ab352227881d00b7