Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
To quickly manage and deploy applications for Kubernetes, you can use the open-source Helm package manager. With Helm, application packages are defined as charts, which are collected and stored in a Helm chart repository.
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
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:
helm registry login
or az acr login
command.helm
commands to push, pull, and manage Helm charts in a registryhelm install
to install charts to a Kubernetes cluster from the registry.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 |
✔️ |
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 | ✔️ |
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:
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.az --version
to find the version. If you need to install or upgrade, see Install Azure CLI.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 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:
cat <<EOF > configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: hello-world-configmap
data:
myvalue: "Hello World"
EOF
For more about creating and running this example, see Getting Started in the Helm Docs.
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
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.
SERVICE_PRINCIPAL_NAME=<acr-helm-sp>
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \
--scopes $(az acr show --name $ACR_NAME --query id --output tsv) \
--role acrpush \
--query "password" --output tsv)
USER_NAME=$(az identity show -n $SERVICE_PRINCIPAL_NAME -g $RESOURCE_GROUP_NAME --subscription $SUBSCRIPTION_ID --query "clientId" -o tsv)
USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
USER_NAME="helmtoken"
PASSWORD=$(az acr token create -n $USER_NAME \
-r $ACR_NAME \
--scope-map _repositories_admin \
--only-show-errors \
--query "credentials.passwords[0].value" -o tsv)
helm registry login
.
helm registry login $ACR_NAME.azurecr.io \
--username $USER_NAME \
--password $PASSWORD
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
:
helm push hello-world-0.1.0.tgz oci://$ACR_NAME.azurecr.io/helm
After a successful push, output is similar to:
Pushed: <registry>.azurecr.io/helm/hello-world:0.1.0
digest: sha256:5899db028dcf96aeaabdadfa5899db02589b2899b025899b059db02
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
Output is similar to:
{
"changeableAttributes": {
"deleteEnabled": true,
"listEnabled": true,
"readEnabled": true,
"writeEnabled": true
},
"createdTime": "2021-10-05T12:11:37.6701689Z",
"imageName": "helm/hello-world",
"lastUpdateTime": "2021-10-05T12:11:37.7637082Z",
"manifestCount": 1,
"registry": "mycontainerregistry.azurecr.io",
"tagCount": 1
}
Run the az acr manifest list-metadata command to see details of the chart stored in the repository. For example:
az acr manifest list-metadata \
--registry $ACR_NAME \
--name helm/hello-world
Output, abbreviated in this example, shows a configMediaType
of application/vnd.cncf.helm.config.v1+json
:
[
{
[...]
"configMediaType": "application/vnd.cncf.helm.config.v1+json",
"createdTime": "2021-10-05T12:11:37.7167893Z",
"digest": "sha256:0c03b71c225c3ddff53660258ea16ca7412b53b1f6811bf769d8c85a1f0663ee",
"imageSize": 3301,
"lastUpdateTime": "2021-10-05T12:11:37.7167893Z",
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"tags": [
"0.1.0"
]
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:
helm install myhelmtest oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0
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
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.
helm pull oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0
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
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
az acr repository
commands to manage the charts. See previous sections in this article.helm search
and helm repo list
. For more information about Helm commands used to store charts as OCI artifacts, see the Helm documentation.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 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...
[...]
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.
Login to the registry:
az acr login --name $ACR_NAME
Push each chart archive to the registry. Example:
helm push ingress-nginx-3.20.1.tgz oci://$ACR_NAME.azurecr.io/helm
After pushing a chart, confirm it is stored in the registry:
az acr repository list --name $ACR_NAME
After pushing all of the charts, optionally remove the Helm 2-style chart repository from the registry. Doing so reduces storage in your registry:
helm repo remove $ACR_NAME
Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Deploy and use Azure Container Registry - Training
Learn how to create a private registry service for building, storing, and managing container images and related artifacts.
Certification
Microsoft Certified: Azure Administrator Associate - Certifications
Demonstrate key skills to configure, manage, secure, and administer key professional functions in Microsoft Azure.