Push and pull Helm charts to an Azure container registry

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. 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.

Important

Support for Helm charts in Azure Container Registry is currently in preview. Previews are made available to you on the condition that you agree to the supplemental terms of use. Some aspects of this feature may change prior to general availability (GA).

Helm 3 or Helm 2?

To store, manage, and install Helm charts, you use a Helm client and the Helm CLI. Major releases of the Helm client 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 create one or more Helm repositories in an Azure container registry
  • Store Helm 3 charts in a registry as OCI artifacts. Currently, Helm 3 support for OCI is experimental.
  • Authenticate with your registry using the helm registry login command.
  • Use helm chart commands in the Helm CLI to push, pull, and manage Helm charts in a registry
  • Use helm install to install charts to a Kubernetes cluster from a local repository cache.

Note

As of Helm 3, az acr helm commands for use with the Helm 2 client are being deprecated. See the product roadmap. If you've previously deployed Helm 2 charts, see Migrating Helm v2 to v3.

Prerequisites

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.1.0 or later - Run helm version to find your current version. For more information on how to install and upgrade Helm, see Installing Helm.
  • A Kubernetes cluster where you will install a Helm chart. If needed, create an Azure Kubernetes Service cluster.
  • 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.

Enable OCI support

Use the helm version command to verify that you have installed Helm 3:

helm version

Set the following environment variable to enable OCI support in the Helm 3 client. Currently, this support is experimental.

export HELM_EXPERIMENTAL_OCI=1

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:

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.

Save chart to local registry cache

Change directory to the hello-world subdirectory. Then, run helm chart save to save a copy of the chart locally and also create an alias with the fully qualified name of the registry (all lowercase) and the target repository and tag.

In the following example, the registry name is mycontainerregistry, the target repo is hello-world, and the target chart tag is v1, but substitute values for your environment:

cd ..
helm chart save . hello-world:v1
helm chart save . mycontainerregistry.azurecr.io/helm/hello-world:v1

Run helm chart list to confirm you saved the charts in the local registry cache. Output is similar to:

REF                                                      NAME            VERSION DIGEST  SIZE            CREATED
hello-world:v1                                           hello-world       0.1.0   5899db0 3.2 KiB        2 minutes 
mycontainerregistry.azurecr.io/helm/hello-world:v1       hello-world       0.1.0   5899db0 3.2 KiB        2 minutes

Authenticate with the registry

Run the helm registry login command in the Helm 3 CLI to authenticate with the registry using credentials appropriate for your scenario.

For example, create an Azure Active Directory service principal with pull and push permissions (AcrPush role) to the registry. Then supply the service principal credentials to helm registry login. The following example supplies the password using an environment variable:

echo $spPassword | helm registry login mycontainerregistry.azurecr.io \
  --username <service-principal-id> \
  --password-stdin

Push chart to registry

Run the helm chart push command in the Helm 3 CLI to push the chart to the fully qualified target repository:

helm chart push mycontainerregistry.azurecr.io/helm/hello-world:v1

After a successful push, output is similar to:

The push refers to repository [mycontainerregistry.azurecr.io/helm/hello-world]
ref:     mycontainerregistry.azurecr.io/helm/hello-world:v1
digest:  5899db028dcf96aeaabdadfa5899db025899db025899db025899db025899db02
size:    3.2 KiB
name:    hello-world
version: 0.1.0

List charts in the repository

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 mycontainerregistry \
  --repository helm/hello-world

Output is similar to:

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2020-03-20T18:11:37.6701689Z",
  "imageName": "helm/hello-world",
  "lastUpdateTime": "2020-03-20T18:11:37.7637082Z",
  "manifestCount": 1,
  "registry": "mycontainerregistry.azurecr.io",
  "tagCount": 1
}

Run the az acr repository show-manifests command to see details of the chart stored in the repository. For example:

az acr repository show-manifests \
  --name mycontainerregistry \
  --repository helm/hello-world --detail

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": "2020-03-20T18:11:37.7167893Z",
    "digest": "sha256:0c03b71c225c3ddff53660258ea16ca7412b53b1f6811bf769d8c85a1f0663ee",
    "imageSize": 3301,
    "lastUpdateTime": "2020-03-20T18:11:37.7167893Z",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "tags": [
      "v1"
    ]

Pull chart to local cache

To install a Helm chart to Kubernetes, the chart must be in the local cache. In this example, first run helm chart remove to remove the existing local chart named mycontainerregistry.azurecr.io/helm/hello-world:v1:

helm chart remove mycontainerregistry.azurecr.io/helm/hello-world:v1

Run helm chart pull to download the chart from the Azure container registry to your local cache:

helm chart pull mycontainerregistry.azurecr.io/helm/hello-world:v1

Export Helm chart

To work further with the chart, export it to a local directory using helm chart export. For example, export the chart you pulled to the install directory:

helm chart export mycontainerregistry.azurecr.io/helm/hello-world:v1 \
  --destination ./install

To view information for the exported chart in the repo, run the helm show chart command in the directory where you exported the chart.

cd install
helm show chart hello-world

Helm returns detailed information about the latest version of your chart, as shown in the following sample output:

apiVersion: v2
appVersion: 1.16.0
description: A Helm chart for Kubernetes
name: hello-world
type: application
version: 0.1.0    

Install Helm chart

Run helm install to install the Helm chart you pulled to the local cache and exported. Specify a release name such as myhelmtest, or pass the --generate-name parameter. For example:

helm install myhelmtest ./hello-world

Output after successful chart installation is similar to:

NAME: myhelmtest
LAST DEPLOYED: Fri Mar 20 14:14:42 2020
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

Delete chart from the registry

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 mycontainerregistry --image helm/hello-world:v1

Next steps