Skip to content

Commit 4fe302c

Browse files
dlepowdlepow
committed
[ACR] Helm updates
1 parent e42ab75 commit 4fe302c

File tree

1 file changed

+102
-95
lines changed

1 file changed

+102
-95
lines changed

‎articles/container-registry/container-registry-helm-repos.md

Lines changed: 102 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@
22
title: Store Helm charts
33
description: Learn how to store Helm charts for your Kubernetes applications using repositories in Azure Container Registry
44
ms.topic: article
5-
ms.date: 01/28/2020
5+
ms.date: 03/20/2020
66
---
77

88
# Push and pull Helm charts to an Azure container registry
99

1010
To quickly manage and deploy applications for Kubernetes, you can use the [open-source Helm package manager][helm]. With Helm, application packages are defined as [charts](https://helm.sh/docs/topics/charts/), which are collected and stored in a [Helm chart repository](https://helm.sh/docs/topics/chart_repository/).
1111

12-
This article shows you how to host Helm charts in repositories in an Azure container registry, using either a Helm 3 or Helm 2 installation. For this example, you store an existing Helm chart from the public Helm *stable* repo. 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][develop-helm-charts].
12+
This article shows you how to host Helm charts repositories in an Azure container registry, using either a Helm 3 or Helm 2 installation. 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][develop-helm-charts]. You can also store an existing Helm chart from another Helm repo.
1313

1414
> [!IMPORTANT]
1515
> 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][terms-of-use]. Some aspects of this feature may change prior to general availability (GA).
@@ -20,12 +20,12 @@ To store, manage, and install Helm charts, you use a Helm client and the Helm CL
2020

2121
You can use either Helm 3 or Helm 2 to host Helm charts in Azure Container Registry, with workflows specific to each version:
2222

23-
* [Helm 3 client](#use-the-helm-3-client) - use `helm chart` commands to manage charts in your registry as [OCI artifacts](container-registry-image-formats.md#oci-artifacts)
23+
* [Helm 3 client](#use-the-helm-3-client) - use `helm chart` commands in the Helm CLI to manage charts in your registry as [OCI artifacts](container-registry-image-formats.md#oci-artifacts)
2424
* [Helm 2 client](#use-the-helm-2-client) - use [az acr helm][az-acr-helm] commands in the Azure CLI to add and manage your container registry as a Helm chart repository
2525

2626
### Additional information
2727

28-
* We recommend using the Helm 3 workflow with native `helm chart` commands to manage charts as OCI artifacts.
28+
* For most scenarios, we recommend using the Helm 3 workflow with native `helm chart` commands to manage charts as OCI artifacts.
2929
* You can use legacy [az acr helm][az-acr-helm] Azure CLI commands and workflow with the Helm 3 client and charts. However, certain commands such as `az acr helm list` aren't compatible with Helm 3 charts.
3030
* As of Helm 3, [az acr helm][az-acr-helm] commands are supported mainly for compatibility with the Helm 2 client and chart format. Future development of these commands isn't currently planned.
3131

@@ -34,7 +34,7 @@ You can use either Helm 3 or Helm 2 to host Helm charts in Azure Container Regis
3434
### Prerequisites
3535

3636
- **An Azure container registry** in your Azure subscription. If needed, create a registry using the [Azure portal](container-registry-get-started-portal.md) or the [Azure CLI](container-registry-get-started-azure-cli.md).
37-
- **Helm client version 3.0.0 or later** - Run `helm version` to find your current version. For more information on how to install and upgrade Helm, see [Installing Helm][helm-install].
37+
- **Helm client version 3.1.1 or later** - Run `helm version` to find your current version. For more information on how to install and upgrade Helm, see [Installing Helm][helm-install].
3838
- **A Kubernetes cluster** where you will install a Helm chart. If needed, create an [Azure Kubernetes Service cluster][aks-quickstart].
3939
- **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][azure-cli-install].
4040

@@ -43,9 +43,9 @@ You can use either Helm 3 or Helm 2 to host Helm charts in Azure Container Regis
4343
With **Helm 3** you:
4444

4545
* Can create one or more Helm repositories in an Azure container registry
46-
* Store Helm 3 charts in a registry as [OCI artifacts](container-registry-image-formats.md#oci-artifacts). Currently, Helm 3 support for OCI is considered *experimental*.
47-
* Use `helm chart` commands directly from the Helm CLI to push, pull, and manage Helm charts in a registry
48-
* Authenticate with your registry via the Azure CLI, which then updates your Helm client automatically with the registry URI and credentials. You don't need to manually specify this registry information, so the credentials aren't exposed in the command history.
46+
* Store Helm 3 charts in a registry as [OCI artifacts](container-registry-image-formats.md#oci-artifacts). Currently, Helm 3 support for OCI is *experimental*.
47+
* Authenticate with your registry using the `helm registry login` command.
48+
* Use `helm chart` commands in the Helm CLI to push, pull, and manage Helm charts in a registry
4949
* Use `helm install` to install charts to a Kubernetes cluster from a local repository cache.
5050

5151
See the following sections for examples.
@@ -58,68 +58,87 @@ Set the following environment variable to enable OCI support in the Helm 3 clien
5858
export HELM_EXPERIMENTAL_OCI=1
5959
```
6060

61-
### Pull an existing Helm package
61+
### Create a sample chart
6262

63-
If you haven't already added the `stable` Helm chart repo, run the `helm repo add` command:
63+
Create a test chart using the following commands:
6464

6565
```console
66-
helm repo add stable https://kubernetes-charts.storage.googleapis.com
66+
mkdir helmtest
67+
68+
cd helmtest
69+
helm create hello-world
6770
```
6871

69-
Pull a chart package from the `stable` repo locally. For example, create a local directory such as *~/acr-helm*, then download the existing *stable/wordpress* chart package. (This example and other commands in this article are formatted for the Bash shell.)
72+
As a basic example, change directory to the `templates` folder and first delete the contents there:
7073

7174
```console
72-
mkdir ~/acr-helm && cd ~/acr-helm
73-
helm pull stable/wordpress --untar
75+
rm -rf *
76+
```
77+
78+
In the `templates` folder, create a file called `configmap.yaml` with the following contents:
79+
80+
```yml
81+
apiVersion: v1
82+
kind: ConfigMap
83+
metadata:
84+
name: hello-world-configmap
85+
data:
86+
myvalue: "Hello World"
7487
```
7588
76-
The `helm pull stable/wordpress` command didn't specify a particular version, so the *latest* version was pulled and uncompressed in the `wordpress` subdirectory.
89+
For more about creating and running this example, see [Getting Started](https://helm.sh/docs/chart_template_guide/getting_started/) in the Helm Docs.
7790
7891
### Save chart to local registry cache
7992
80-
Change directory to the `wordpress` subdirectory, which contains the Helm chart files. 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 and the target repository and tag.
93+
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.
8194

82-
In the following example, the registry name is *mycontainerregistry*, the target repo is *wordpress*, and the target chart tag is *latest*, but substitute values for your environment:
95+
In the following example, the registry name is *mycontainerregistry*, the target repo is *wordpress*, and the target chart tag is *v1*, but substitute values for your environment:
8396

8497
```console
85-
cd wordpress
86-
helm chart save . wordpress:latest
87-
helm chart save . mycontainerregistry.azurecr.io/helm/wordpress:latest
98+
cd ..
99+
helm chart save . hello-world:v1
100+
helm chart save . mycontainerregistry.azurecr.io/helm/hello-world:v1
88101
```
89102

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

92105
```console
93106
REF NAME VERSION DIGEST SIZE CREATED
94-
wordpress:latest wordpress 8.1.0 5899db0 29.1 KiB 1 day
95-
mycontainerregistry.azurecr.io/helm/wordpress:latest wordpress 8.1.0 5899db0 29.1 KiB 1 day
107+
hello-world:v1 hello-world 0.1.0 5899db0 3.2 KiB 2 minutes
108+
mycontainerregistry.azurecr.io/helm/hello-world:v1 hello-world 0.1.0 5899db0 3.2 KiB 2 minutes
96109
```
97110

98-
### Push chart to Azure Container Registry
111+
### Authenticate with the registry
99112

100-
Run the `helm chart push` command in the Helm 3 CLI to push the Helm chart to a repository in your Azure container registry. If it doesn't exist, the repository is created.
113+
Run the `helm registry login` command in the Helm 3 CLI to [authenticate with the registry](container-registry-authentication.md) using credentials appropriate for your scenario.
101114

102-
First use the Azure CLI command [az acr login][az-acr-login] to authenticate to your registry:
115+
For example, create an Azure Active Directory [service principal with pull and push permissions](container-registry-auth-service-principalmd#create-a-service-principal) (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:
103116

104-
```azurecli
105-
az acr login --name mycontainerregistry
117+
```console
118+
echo $spPassword | helm registry login mycontainerregistry.azurecr.io \
119+
--username <service-principal-id> \
120+
--password-stdin
106121
```
107122

123+
### Push chart to Azure Container Registry
124+
125+
Run the `helm chart push` command in the Helm 3 CLI to push the Helm chart to a repository in your Azure container registry. If it doesn't exist, the repository is created.
126+
108127
Push the chart to the fully qualified target repository:
109128

110129
```console
111-
helm chart push mycontainerregistry.azurecr.io/helm/wordpress:latest
130+
helm chart push mycontainerregistry.azurecr.io/helm/hello-world:v1
112131
```
113132

114133
After a successful push, output is similar to:
115134

116135
```output
117136
The push refers to repository [mycontainerregistry.azurecr.io/helm/wordpress]
118-
ref: mycontainerregistry.azurecr.io/helm/wordpress:latest
137+
ref: mycontainerregistry.azurecr.io/helm/hello-world:v1
119138
digest: 5899db028dcf96aeaabdadfa5899db025899db025899db025899db025899db02
120-
size: 29.1 KiB
121-
name: wordpress
122-
version: 8.1.0
139+
size: 3.2 KiB
140+
name: hello-world
141+
version: 0.1.0
123142
```
124143

125144
### List charts in the repository
@@ -131,7 +150,7 @@ For example, run [az acr repository show][az-acr-repository-show] to see the pro
131150
```azurecli
132151
az acr repository show \
133152
--name mycontainerregistry \
134-
--repository helm/wordpress
153+
--repository helm/hello-world
135154
```
136155

137156
Output is similar to:
@@ -144,11 +163,11 @@ Output is similar to:
144163
"readEnabled": true,
145164
"writeEnabled": true
146165
},
147-
"createdTime": "2020-01-29T16:54:30.1514833Z",
148-
"imageName": "helm/wordpress",
149-
"lastUpdateTime": "2020-01-29T16:54:30.4992247Z",
166+
"createdTime": "2020-03-20T18:11:37.6701689Z",
167+
"imageName": "helm/hello-world",
168+
"lastUpdateTime": "2020-03-20T18:11:37.7637082Z",
150169
"manifestCount": 1,
151-
"registry": "mycontainerregistry.azurecr.io",
170+
"registry": "danlep0318.azurecr.io",
152171
"tagCount": 1
153172
}
154173
```
@@ -158,7 +177,7 @@ Run the [az acr repository show-manifests][az-acr-repository-show-manifests] com
158177
```azurecli
159178
az acr repository show-manifests \
160179
--name mycontainerregistry \
161-
--repository helm/wordpress --detail
180+
--repository helm/hello-world --detail
162181
```
163182

164183
Output, abbreviated in this example, shows a `configMediaType` of `application/vnd.cncf.helm.config.v1+json`:
@@ -168,102 +187,90 @@ Output, abbreviated in this example, shows a `configMediaType` of `application/v
168187
{
169188
[...]
170189
"configMediaType": "application/vnd.cncf.helm.config.v1+json",
171-
"createdTime": "2020-01-29T16:54:30.2382436Z",
172-
"digest": "sha256:xxxxxxxx51bc0807bfa97cb647e493ac381b96c1f18749b7388c24bbxxxxxxxxx",
173-
"imageSize": 29995,
174-
"lastUpdateTime": "2020-01-29T16:54:30.3492436Z",
190+
"createdTime": "2020-03-20T18:11:37.7167893Z",
191+
"digest": "sha256:0c03b71c225c3ddff53660258ea16ca7412b53b1f6811bf769d8c85a1f0663ee",
192+
"imageSize": 3301,
193+
"lastUpdateTime": "2020-03-20T18:11:37.7167893Z",
175194
"mediaType": "application/vnd.oci.image.manifest.v1+json",
176195
"tags": [
177-
"latest"
196+
"v1"
178197
]
179-
}
180-
]
181198
```
182199

183200
### Pull chart to local cache
184201

185202
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/wordpress:latest`:
186203

187204
```console
188-
helm chart remove mycontainerregistry.azurecr.io/helm/wordpress:latest
205+
helm chart remove mycontainerregistry.azurecr.io/helm/hello-world:v1
189206
```
190207

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

193210
```console
194-
helm chart pull mycontainerregistry.azurecr.io/helm/wordpress:latest
211+
helm chart pull mycontainerregistry.azurecr.io/helm/hello-world:v1
195212
```
196213

197214
### Export Helm chart
198215

199216
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:
200217

201218
```console
202-
helm chart export mycontainerregistry.azurecr.io/helm/wordpress:latest --destination ./install
219+
helm chart export mycontainerregistry.azurecr.io/helm/hello-world:v1 \
220+
--destination ./install
203221
```
204222

205-
To view information for the exported chart in the repo, run the `helm inspect chart` command in the directory where you exported the chart.
223+
To view information for the exported chart in the repo, run the `helm show chart` command in the directory where you exported the chart.
206224

207225
```console
208226
cd install
209-
helm inspect chart wordpress
227+
helm show chart hello-world
210228
```
211229

212-
When no version number is provided, the *latest* version is used. Helm returns detailed information about your chart, as shown in the following condensed output:
230+
Helm returns detailed information about the latest version of your chart, as shown in the following sample output:
213231

214232
```output
215-
apiVersion: v1
216-
appVersion: 5.3.2
217-
dependencies:
218-
- condition: mariadb.enabled
219-
name: mariadb
220-
repository: https://kubernetes-charts.storage.googleapis.com/
221-
tags:
222-
- wordpress-database
223-
version: 7.x.x
224-
description: Web publishing platform for building blogs and websites.
225-
home: http://www.wordpress.com/
226-
icon: https://bitnami.com/assets/stacks/wordpress/img/wordpress-stack-220x234.png
227-
keywords:
228-
- wordpress
229-
- cms
230-
- blog
231-
- http
232-
- web
233-
- application
234-
- php
235-
maintainers:
236-
- email: [email protected]
237-
name: Bitnami
238-
name: wordpress
239-
sources:
240-
- https://github.com/bitnami/bitnami-docker-wordpress
241-
version: 8.1.0
233+
apiVersion: v2
234+
appVersion: 1.16.0
235+
description: A Helm chart for Kubernetes
236+
name: hello-world
237+
type: application
238+
version: 0.1.0
242239
```
243240

244241
### Install Helm chart
245242

246-
Run `helm install` to install the Helm chart you pulled to the local cache and exported. Specify a release name or pass the `--generate-name` parameter. For example:
243+
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:
247244

248245
```console
249-
helm install wordpress --generate-name
246+
helm install myhelmtest ./hello-world
250247
```
251248

252-
As the installation proceeds, follow the instructions in the command output to see the WorPress URLs and credentials. You can also run the `kubectl get pods` command to see the Kubernetes resources deployed through the Helm chart:
249+
Output after successful chart installation is similar to:
253250

254-
```output
255-
NAME READY STATUS RESTARTS AGE
256-
wordpress-1598530621-67c77b6d86-7ldv4 1/1 Running 0 2m48s
257-
wordpress-1598530621-mariadb-0 1/1 Running 0 2m48s
258-
[...]
251+
```console
252+
NAME: myhelmtest
253+
LAST DEPLOYED: Fri Mar 20 14:14:42 2020
254+
NAMESPACE: default
255+
STATUS: deployed
256+
REVISION: 1
257+
TEST SUITE: None
258+
```
259+
260+
To verify the installation, run the `helm get manifest` command. The command returns the YAML data in your `configmap.yaml` template file.
261+
262+
Run `helm uninstall` to uninstall the chart release on your cluster:
263+
264+
```console
265+
helm uninstall myhelmtest
259266
```
260267

261268
### Delete a Helm chart from the repository
262269

263270
To delete a chart from the repository, use the [az acr repository delete][az-acr-repository-delete] command. Run the following command and confirm the operation when prompted:
264271

265272
```azurecli
266-
az acr repository delete --name mycontainerregistry --image helm/wordpress:latest
273+
az acr repository delete --name mycontainerregistry --image helm/hello-world:v1
267274
```
268275

269276
## Use the Helm 2 client
@@ -279,9 +286,9 @@ az acr repository delete --name mycontainerregistry --image helm/wordpress:lates
279286
With **Helm 2** you:
280287

281288
* Configure your Azure container registry as a *single* Helm chart repository. Azure Container Registry manages the index definition as you add and remove charts to the repository.
289+
* Authenticate with your Azure container registry via the Azure CLI, which then updates your Helm client automatically with the registry URI and credentials. You don't need to manually specify this registry information, so the credentials aren't exposed in the command histor
282290
* Use the [az acr helm][az-acr-helm] commands in the Azure CLI to add your Azure container registry as a Helm chart repository, and to push and manage charts. These Azure CLI commands wrap Helm 2 client commands.
283-
* Add the chart repository in your Azure container registry to your local Helm repo index, supporting chart search
284-
* Authenticate with your Azure container registry via the Azure CLI, which then updates your Helm client automatically with the registry URI and credentials. You don't need to manually specify this registry information, so the credentials aren't exposed in the command history.
291+
* Add the chart repository in your Azure container registry to your local Helm repo index, supporting chart search.
285292
* Use `helm install` to install charts to a Kubernetes cluster from a local repository cache.
286293

287294
See the following sections for examples.
@@ -294,7 +301,7 @@ Add your Azure Container Registry Helm chart repository to your Helm client usin
294301
az acr helm repo add --name mycontainerregistry
295302
```
296303

297-
### Add a chart to the repository
304+
### Add a sample chart to the repository
298305

299306
First, create a local directory at *~/acr-helm*, then download the existing *stable/wordpress* chart:
300307

@@ -341,8 +348,8 @@ helm search mycontainerregistry
341348
The Wordpress chart pushed in the previous step is listed, as shown in the following example output:
342349

343350
```output
344-
NAME CHART VERSION APP VERSION DESCRIPTION
345-
helmdocs/wordpress 8.1.0 5.3.2 Web publishing platform for building blogs and websites.
351+
NAME CHART VERSION APP VERSION DESCRIPTION
352+
helmdocs/wordpress 8.1.0 5.3.2 Web publishing platform for building blogs and websites.
346353
```
347354

348355
You can also list the charts with the Azure CLI, using [az acr helm list][az-acr-helm-list]:
@@ -436,9 +443,9 @@ az acr helm repo add --name mycontainerregistry
436443

437444
## Next steps
438445

439-
This article used an existing Helm chart from the public *stable* repository. For more information on how to create and deploy Helm charts, see [Developing Helm charts][develop-helm-charts].
440-
441-
Helm charts can be used as part of the container build process. For more information, see [Use Azure Container Registry Tasks][acr-tasks].
446+
* For more information on how to create and deploy Helm charts, see [Developing Helm charts][develop-helm-charts].
447+
* Learn more about installing applications with Helm in [Azure Kubernetes Service (AKS)](../aks/kubernetes-helm.md).
448+
* Helm charts can be used as part of the container build process. For more information, see [Use Azure Container Registry Tasks][acr-tasks].
442449

443450
<!-- LINKS - external -->
444451
[helm]: https://helm.sh/

0 commit comments

Comments
 (0)