Pushen und Pullen von Helm-Charts in Azure Container Registry

  • Artikel

Sie können den Open Source-Paket-Manager von Helm verwenden, um Anwendungen für Kubernetes ohne großen Aufwand zu verwalten und bereitzustellen. Bei Helm werden Anwendungspakete als Charts definiert, die gesammelt und in einem Helm-Chartrepository gespeichert werden.

In diesem Artikel erfahren Sie, wie Sie mithilfe von Helm 3-Befehlen und durch Speichern von Charts als OCI-Artefakte Helm-Chartrepositorys in einer Azure-Containerregistrierung hosten. In vielen Szenarien würden Sie für Ihre selbst entwickelten Anwendungen eigene Charts erstellen und hochladen. Weitere Informationen zum Erstellen eigener Helm-Charts finden Sie unter Entwicklerhandbuch für Chartvorlagen. Sie können auch ein vorhandenes Helm-Chart aus einem anderen Helm-Repository speichern.

Wichtig

Zur Aktualisierung wurden Helm 3-Befehle in diesen Artikel aufgenommen. Helm 3.7 enthält Änderungen an Helm CLI-Befehlen und der OCI-Unterstützung, die in früheren Versionen von Helm 3 eingeführt wurden. Von Haus aus wird helm mit jeder Version weiterentwickelt. Es wird empfohlen, 3.7.2 oder höher zu verwenden.

Helm 3 oder Helm 2?

Zum Speichern, Verwalten und Installieren von Helm-Charts verwenden Sie Befehle in der Helm-Befehlszeilenschnittstelle. Hauptreleases von Helm umfassen Helm 3 und Helm 2. Ausführliche Informationen zu den Versionsunterschieden finden Sie in den häufig gestellten Fragen (FAQ) zur Version.

Helm 3 sollte zum Hosten von Helm-Charts in Azure Container Registry verwendet werden. Mit Helm 3 haben Sie folgende Möglichkeiten:

  • Speichern und Verwalten von Helm-Charts in Repositorys in einer Azure-Containerregistrierung.
  • Speichern von Helm-Charts in einer Registrierung als OCI-Artefakte. Azure Container Registry bietet allgemeine Unterstützung für OCI-Artefakte, einschließlich Helm-Charts.
  • Authentifizieren bei Ihrer Registrierung mithilfe des Befehls helm registry login oder az acr login.
  • Pushen, Pullen und Verwalten von Helm-Charts in einer Registrierung mithilfe von helm-Befehlen.
  • Verwenden Sie helm install, um Charts aus der Registrierung in einem Kubernetes-Cluster zu installieren.

Featureunterstützung

Azure Container Registry unterstützt bestimmte Verwaltungsfeatures für Helm-Charts, je nachdem, ob Sie Helm 3 (aktuell) oder Helm 2 (veraltet) verwenden.

Komponente Helm 2 Helm 3
Verwalten von Charts mithilfe von az acr helm-Befehlen ✔️
Speichern von Charts als OCI-Artefakte ✔️
Verwalten von Charts mithilfe von az acr repository-Befehlen und über das Blatt Repositorys im Azure-Portal ✔️

Hinweis

Ab Helm 3 gelten az acr helm-Befehle für die Verwendung mit dem Helm 2-Client als veraltet. Sie werden mindestens drei Monate im Voraus über das Entfernen eines Befehls informiert.

Kompatibilität von Chartversionen

Die folgenden Helm-Chartversionen können in Azure Container Registry gespeichert und von den Helm 2- und Helm 3-Clients installiert werden.

Version Helm 2 Helm 3
apiVersion v1 ✔️ ✔️
apiVersion v2 ✔️

Migrieren von Helm 2 zu Helm 3

Wenn Sie zuvor Charts mithilfe von Helm 2 und Azure Container Registry gespeichert und bereitgestellt haben, empfiehlt sich eine Migration zu Helm 3. Thema

Voraussetzungen

Die folgenden Ressourcen sind für das Szenario in diesem Artikel erforderlich:

Einrichten eines Helm-Clients

Verwenden Sie den Befehl helm version, um zu überprüfen, ob Sie Helm 3 installiert haben:

helm version

Hinweis

Die angegebene Version muss mindestens 3.8.0 sein, da die OCI-Unterstützung in früheren Versionen experimentell war.

Legen Sie die folgenden Umgebungsvariablen für die Zielregistrierung fest. Der ACR_NAME ist der Name der Registrierungsressource. Wenn die URL der ACR-Registrierung myregistry.azurecr.io ist, legen Sie ACR_NAME auf myregistry fest.

ACR_NAME=<container-registry-name>

Erstellen eines Beispielcharts

Erstellen Sie mithilfe der folgenden Befehle ein Testchart:

mkdir helmtest

cd helmtest
helm create hello-world

Wechseln Sie für dieses einfache Beispiel zunächst in den Ordner templates, und löschen Sie den Inhalt des Ordners:

cd hello-world/templates
rm -rf *

Erstellen Sie im Ordner templates eine Datei namens configmap.yaml, indem Sie den folgenden Befehl ausführen:

cat <<EOF > configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-world-configmap
data:
  myvalue: "Hello World"
EOF

Weitere Informationen zum Erstellen und Ausführen dieses Beispiels finden Sie in der Helm-Dokumentation unter Erste Schritte.

Speichern eines Charts im lokalen Archiv

Wechseln Sie in das Unterverzeichnis hello-world. Führen Sie dann helm package aus, um das Chart in einem lokalen Archiv zu speichern.

Im folgenden Beispiel wird das Chart mit dem Namen und der Version in Chart.yaml gespeichert.

cd ..
helm package .

Die Ausgabe Die Ausgabe lautet in etwa wie folgt:

Successfully packaged chart and saved it to: /my/path/hello-world-0.1.0.tgz

Authentifizieren bei der Registrierung

Führen Sie helm registry login aus, um sich bei der Registrierung zu authentifizieren. Sie können für Ihr Szenario geeignete Registrierungsanmeldeinformationen übergeben, z. B. Anmeldeinformationen für den Dienstprinzipal, die Benutzeridentität oder ein Token für den Repositorygültigkeitsbereich.

  • Authentifizieren Sie sich für die Registrierung mit einem Microsoft Entra-Dienstprinzipal mit Pull- und Pushberechtigung (Rolle „AcrPush“). 
    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)
  • Sie können sich bei der Registrierung auch mit Ihrer persönlichen Microsoft Entra-Identität anmelden, um Helm-Charts mit einem AD-Token zu pushen und zu pullen. 
    USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
  • Authentifizieren mit einem Token für den Repositorygültigkeitsbereich (Vorschau). 
    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)
  • Stellen Sie die Anmeldeinformationen für helm registry login bereit. 
    helm registry login $ACR_NAME.azurecr.io \
  --username $USER_NAME \
  --password $PASSWORD

Pushen eines Charts als OCI-Artefakt in die Registrierung

Führen Sie den Befehl helm push in der Helm 3-Befehlszeilenschnittstelle aus, um das Chartarchiv in das vollqualifizierte Zielrepository zu pushen. Trennen Sie die Wörter in den Diagrammnamen, und verwenden Sie nur Kleinbuchstaben und Zahlen. Im folgenden Beispiel lautet der Ziel-Repositorynamespace helm/hello-world, und das Chart ist mit 0.1.0 gekennzeichnet:

helm push hello-world-0.1.0.tgz oci://$ACR_NAME.azurecr.io/helm

Nach einem erfolgreichen Push ähnelt die Ausgabe der folgenden:

Pushed: <registry>.azurecr.io/helm/hello-world:0.1.0
digest: sha256:5899db028dcf96aeaabdadfa5899db02589b2899b025899b059db02

Auflisten von Diagrammen im Repository

Wie bei in Azure Container Registry gespeicherten Images können Sie mithilfe von az acr repository-Befehlen die Depots anzeigen, in denen Ihre Charts gehostet werden, sowie die Charttags und -manifeste.

Führen Sie z. B. az acr repository show aus, um die Eigenschaften des im vorherigen Schritt erstellten Repositorys anzuzeigen:

az acr repository show \
  --name $ACR_NAME \
  --repository helm/hello-world

Die Ausgabe Die Ausgabe lautet in etwa wie folgt:

{
  "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
}

Führen Sie den Befehl az acr manifest list-metadata aus, um die Details des im Repository gespeicherten Diagramms anzuzeigen. Beispiel:

az acr manifest list-metadata \
  --registry $ACR_NAME \
  --name helm/hello-world

Die Ausgabe (in diesem Beispiel abgekürzt) zeigt application/vnd.cncf.helm.config.v1+json als configMediaType an:

[
  {
    [...]
    "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"
    ]

Installieren von Helm-Charts

Führen Sie helm install aus, um das Helm-Chart zu installieren, das Sie in die Registrierung gepusht haben. Das Charttag wird mithilfe des Parameters --version übergeben. Geben Sie einen Releasenamen (beispielsweise myhelmtest) an, oder übergeben Sie den Parameter --generate-name. Beispiel:

helm install myhelmtest oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

Die Ausgabe nach erfolgreicher Chartinstallation sieht in etwa wie folgt aus:

NAME: myhelmtest
LAST DEPLOYED: Tue Oct  4 16:59:51 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

Führen Sie den Befehl helm get manifest aus, um die Installation zu überprüfen.

helm get manifest myhelmtest

Der Befehl gibt die YAML-Daten in der Vorlagendatei configmap.yaml zurück.

Führen Sie helm uninstall aus, um das Chart-Release in Ihrem Cluster zu deinstallieren:

helm uninstall myhelmtest

Pullen eines Charts in das lokale Archiv

Optional können Sie ein Chart mithilfe von helm pull aus der Containerregistrierung in ein lokales Archiv pullen. Das Charttag wird mithilfe des Parameters --version übergeben. Wenn ein lokales Archiv im aktuellen Pfad vorhanden ist, wird es durch diesen Befehl überschrieben.

helm pull oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

Löschen eines Charts aus der Registrierung

Wenn Sie ein Chart aus der Containerregistrierung löschen möchten, verwenden Sie den Befehl az acr repository delete. Führen Sie den folgenden Befehl aus, und bestätigen Sie den Vorgang, wenn Sie dazu aufgefordert werden:

az acr repository delete --name $ACR_NAME --image helm/hello-world:0.1.0

Migrieren Ihrer Registrierung zum Speichern von Helm-OCI-Artefakten

Wenn Sie Ihre Azure-Containerregistrierung zuvor mit Helm 2 und den az acr helm-Befehlen als Chartrepository eingerichtet haben, wird empfohlen, ein Upgrade auf den Helm 3-Client auszuführen. Führen Sie dann die folgenden Schritte aus, um die Charts als OCI-Artefakte in Ihrer Registrierung zu speichern.

Wichtig

  • Nachdem Sie die Migration von einem Helm 2-Chartrepository (index.yaml-basiert) zu OCI-Artefaktrepositorys abgeschlossen haben, verwenden Sie die Helm-Befehlszeilenschnittstelle und die az acr repository-Befehle, um die Charts zu verwalten. Informationen hierzu finden Sie in den früheren Abschnitten dieses Artikels.
  • Die Helm-OCI-Artefaktrepositorys können nicht mit Helm-Befehlen wie helm search und helm repo list gefunden werden. Weitere Informationen zu Helm-Befehlen zum Speichern von Charts als OCI-Artefakte finden Sie in der Helm-Dokumentation.

Aktivieren der OCI-Unterstützung (standardmäßig in Helm v3.8.0 aktiviert)

Stellen Sie sicher, dass Sie den Helm 3-Client verwenden:

helm version

Wenn Sie Helm v3.8.0 oder höher verwenden, ist dies standardmäßig aktiviert. Wenn Sie eine niedrigere Version verwenden, können Sie die OCI-Supporteinstellung durch Festlegen der Umgebungsvariable aktivieren:

export HELM_EXPERIMENTAL_OCI=1

Auflisten aktueller Charts

Listen Sie die Charts auf, die derzeit in der Registrierung gespeichert sind, hier als myregistry benannt:

helm search repo myregistry

Die Ausgabe zeigt die Charts und Chartversionen:

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

Lokales Pullen von Chartarchiven

Pullen Sie für jedes Chart im Repository das Chartarchiv lokal, und notieren Sie sich den Dateinamen:

helm pull myregisry/ingress-nginx
ls *.tgz

Ein lokales Chartarchiv wie ingress-nginx-3.20.1.tgz wird erstellt.

Pushen von Charts als OCI-Artefakte in eine Registrierung

Melden Sie sich bei der Registrierung an:

az acr login --name $ACR_NAME

Pushen Sie jedes Chartarchiv in die Registrierung. Beispiel:

helm push ingress-nginx-3.20.1.tgz oci://$ACR_NAME.azurecr.io/helm

Vergewissern Sie sich nach dem Pushen eines Charts, dass es in der Registrierung gespeichert ist:

az acr repository list --name $ACR_NAME

Entfernen Sie nach dem Pushen aller Charts optional das Helm 2-Chartrepository aus der Registrierung. Dadurch wird der beanspruchte Speicher in Ihrer Registrierung reduziert:

helm repo remove $ACR_NAME

Nächste Schritte

  • Weitere Informationen zum Erstellen und Bereitstellen von Helm-Charts finden Sie unter Charts.
  • Weitere Informationen zum Installieren von Anwendungen mit Helm in Azure Kubernetes Service (AKS) finden Sie hier.
  • Helm-Diagramme können als Teil des Containererstellungsprozesses verwendet werden. Weitere Informationen finden Sie unter Verwenden von Azure Container Registry Tasks.