This article shows you how to host Helm charts repositories in an Azure container registry, using Helm 3 commands and storing charts as OCI artifacts. In many scenarios, you would build and upload your own charts for the applications you develop. For more information on how to build your own Helm charts, see the Chart Template Developer's Guide. You can also store an existing Helm chart from another Helm repo.
Note
This article has been updated with Helm 3 commands. Helm 3.7 includes changes to Helm CLI commands and OCI support introduced in earlier versions of Helm 3. By design helm advances with version updates. We recommend using 3.7.2 or later.
Important
In November 2020, Helm 2 reached end of life. Starting on March 30th, 2025 Azure Container Registry will no longer support Helm 2. Therefore, the legacy "Helm repositories" functionality will also be retired. We recommend that you transition to Helm 3 immediately.
Starting January 21st, 2025 the CLI command az acr helm push will be retired to prevent pushing new Helm charts to legacy Helm repositories.
Starting March 30th, 2025 the CLI command group az acr helm will be retired, ending all legacy Helm repository capabilities in Azure Container Registry.
All Helm charts not stored as an OCI artifact will be deleted from Azure Container Registry on March 30th, 2025.
Learn how to find all Helm charts stored in a Helm repository here: az acr helm list. If the Helm chart you are using is listed then it is stored in a legacy Helm repository and is at risk of deletion.
Helm 3 or Helm 2?
To store, manage, and install Helm charts, you use commands in the Helm CLI. Major Helm releases include Helm 3 and Helm 2. For details on the version differences, see the version FAQ.
Helm 3 should be used to host Helm charts in Azure Container Registry. With Helm 3, you:
Can store and manage Helm charts in repositories in an Azure container registry
Store Helm charts in your registry as OCI artifacts. Azure Container Registry provides GA support for OCI artifacts, including Helm charts.
Authenticate with your registry using the helm registry login or az acr login command.
Use helm commands to push, pull, and manage Helm charts in a registry
Use helm install to install charts to a Kubernetes cluster from the registry.
Feature support
Azure Container Registry supports specific Helm chart management features depending on whether you are using Helm 3 (current) or Helm 2 (deprecated).
Feature
Helm 2
Helm 3
Manage charts using az acr helm commands
✔️
Store charts as OCI artifacts
✔️
Manage charts using az acr repository commands and the Repositories blade in Azure portal
✔️
Chart version compatibility
The following Helm chart versions can be stored in Azure Container Registry and are installable by the Helm 2 and Helm 3 clients.
Version
Helm 2
Helm 3
apiVersion v1
✔️
✔️
apiVersion v2
✔️
Migrate from Helm 2 to Helm 3
If you've previously stored and deployed charts using Helm 2 and Azure Container Registry, we recommend migrating to Helm 3. See:
The following resources are needed for the scenario in this article:
An Azure container registry in your Azure subscription. If needed, create a registry using the Azure portal or the Azure CLI.
Helm client version 3.7 or later - Run helm version to find your current version. For more information on how to install and upgrade Helm, see Installing Helm. If you upgrade from an earlier version of Helm 3, review the release notes.
Azure CLI version 2.0.71 or later - Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.
Set up Helm client
Use the helm version command to verify that you have installed Helm 3:
helm version
Note
The version indicated must be at least 3.8.0, as OCI support in earlier versions was experimental.
Set the following environment variables for the target registry. The ACR_NAME is the registry resource name. If the ACR registry url is myregistry.azurecr.io, set the ACR_NAME to myregistry
ACR_NAME=<container-registry-name>
Create a sample chart
Create a test chart using the following commands:
mkdir helmtest
cd helmtest
helm create hello-world
As a basic example, change directory to the templates folder and first delete the contents there:
cd hello-world/templates
rm -rf *
In the templates folder, create a file called configmap.yaml, by running the following command:
For more about creating and running this example, see Getting Started in the Helm Docs.
Save chart to local archive
Change directory to the hello-world subdirectory. Then, run helm package to save the chart to a local archive.
In the following example, the chart is saved with the name and version in Chart.yaml.
cd ..
helm package .
Output is similar to:
Successfully packaged chart and saved it to: /my/path/hello-world-0.1.0.tgz
Authenticate with the registry
Run helm registry login to authenticate with the registry. You may pass registry credentials appropriate for your scenario, such as service principal credentials, user identity, or a repository-scoped token.
Run the helm push command in the Helm 3 CLI to push the chart archive to the fully qualified target repository. Separate the words in the chart names and use only lower case letters and numbers. In the following example, the target repository namespace is helm/hello-world, and the chart is tagged 0.1.0:
As with images stored in an Azure container registry, you can use az acr repository commands to show the repositories hosting your charts, and chart tags and manifests.
For example, run az acr repository show to see the properties of the repo you created in the previous step:
az acr repository show \
--name $ACR_NAME \
--repository helm/hello-world
Run helm install to install the Helm chart you pushed to the registry. The chart tag is passed using the --version parameter. Specify a release name such as myhelmtest, or pass the --generate-name parameter. For example:
Output after successful chart installation is similar to:
NAME: myhelmtest
LAST DEPLOYED: Tue Oct 4 16:59:51 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
To verify the installation, run the helm get manifest command.
helm get manifest myhelmtest
The command returns the YAML data in your configmap.yaml template file.
Run helm uninstall to uninstall the chart release on your cluster:
helm uninstall myhelmtest
Pull chart to local archive
You can optionally pull a chart from the container registry to a local archive using helm pull. The chart tag is passed using the --version parameter. If a local archive exists at the current path, this command overwrites it.
To delete a chart from the container registry, use the az acr repository delete command. Run the following command and confirm the operation when prompted:
az acr repository delete --name $ACR_NAME --image helm/hello-world:0.1.0
Migrate your registry to store Helm OCI artifacts
If you previously set up your Azure container registry as a chart repository using Helm 2 and the az acr helm commands, we recommend that you upgrade to the Helm 3 client. Then, follow these steps to store the charts as OCI artifacts in your registry.
Important
After you complete migration from a Helm 2-style (index.yaml-based) chart repository to OCI artifact repositories, use the Helm CLI and az acr repository commands to manage the charts. See previous sections in this article.
The Helm OCI artifact repositories are not discoverable using Helm commands such as helm search and helm repo list. For more information about Helm commands used to store charts as OCI artifacts, see the Helm documentation.
Enable OCI support (enabled by default in Helm v3.8.0)
Ensure that you are using the Helm 3 client:
helm version
If you are using Helm v3.8.0 or higher, this is enabled by default. If you are using a lower version, you can enable OCI support setting the environment variable:
export HELM_EXPERIMENTAL_OCI=1
List current charts
List the charts currently stored in the registry, here named myregistry:
helm search repo myregistry
Output shows the charts and chart versions:
NAME CHART VERSION APP VERSION DESCRIPTION
myregistry/ingress-nginx 3.20.1 0.43.0 Ingress controller for Kubernetes...
myregistry/wordpress 9.0.3 5.3.2 Web publishing platform for building...
[...]
Pull chart archives locally
For each chart in the repo, pull the chart archive locally, and take note of the filename:
helm pull myregisry/ingress-nginx
ls *.tgz
A local chart archive such as ingress-nginx-3.20.1.tgz is created.