Schnellstart: Erstellen einer privaten Containerregistrierung mit der Azure CLI

2025-06-05

Azure Container Registry ist ein privater Registrierungsdienst zum Erstellen, Speichern und Verwalten von Containerimages und verwandten Artefakten. In dieser Schnellstartanleitung erstellen Sie eine Azure Container Registry-Instanz mit der Azure CLI. Übertragen Sie anschließend mithilfe von Docker-Befehlen ein Containerimage per Push in die Registrierung. Rufen Sie abschließend das Image per Pull aus der Registrierung ab, und führen Sie es aus.

Für diese Schnellstartanleitung müssen Sie die Azure-Befehlszeilenschnittstelle (Version 2.0.55 empfohlen) ausführen. Führen Sie az --version aus, um die Version zu ermitteln. Informationen zum Durchführen einer Installation oder eines Upgrades finden Sie bei Bedarf unter Installieren der Azure CLI.

Darüber hinaus muss Docker lokal installiert sein. Für Docker sind Pakete erhältlich, mit denen Docker auf einem macOS-, Windows- oder Linux-System problemlos konfiguriert werden kann.

Da Azure Cloud Shell nicht alle erforderlichen Docker-Komponenten (z.B. den dockerd-Daemon) enthält, können Sie Cloud Shell für diesem Schnellstart nicht verwenden.

Erstellen einer Ressourcengruppe

Erstellen Sie mithilfe des Befehls az group create eine Ressourcengruppe. Eine Azure-Ressourcengruppe ist ein logischer Container, in dem Azure-Ressourcen bereitgestellt und verwaltet werden.

Das folgende Beispiel erstellt eine Ressourcengruppe mit dem Namen myResourceGroup am Standort eastus.

az group create --name myResourceGroup --location eastus

Konfigurieren von Parametern für eine Containerregistrierung

In dieser Schnellstartanleitung erstellen Sie eine Standardregistrierung , die für die meisten Azure Container Registry-Workflows ausreichend ist. Ausführliche Informationen zu verfügbaren Dienstebenen finden Sie unter Container Registry-Dienstebenen.

Erstellen Sie mithilfe des Befehls az acr create eine ACR-Instanz. Der Registrierungsname muss innerhalb von Azure eindeutig sein und 5 bis 50 alphanumerische Kleinbuchstaben umfassen. Im folgenden Beispiel wird mycontainerregistry verwendet. Ersetzen Sie diesen Namen durch einen eindeutigen Wert.

DNL-Option (Domain Name Label) konfigurieren

Das Feature Domain Name Label (DNL) stärkt die Sicherheit, indem Subdomänenübernahmeangriffe von Registrierungs-DNS-Namen verhindert werden. Diese Angriffe treten auf, wenn eine Registrierung gelöscht wird, und eine andere Entität verwendet denselben Registrierungsnamen, wodurch nachgeschaltete Verweise möglicherweise aus der Registrierung abgerufen werden, die von der anderen Entität neu erstellt wurden.

DNL behebt dies durch Anfügen eines eindeutigen Hashs an den DNS-Namen der Registrierung. Dadurch wird sichergestellt, dass sich die DNS-Namen aufgrund des eindeutigen Hashs auch dann unterscheiden, wenn derselbe Registrierungsname von einer anderen Entität wiederverwendet wird. Dadurch wird sichergestellt, dass Ihre nachgelagerten Verweise nicht versehentlich auf das von der anderen Entität neu erstellte Registry verweisen.

Beim Erstellen einer Registrierung über den Befehl "az acr create " können Sie das optionale Flag --dnl-scope angeben und aus den verfügbaren Optionen auswählen:

Unsecure: Erstellt den DNS-Namen as-is, basierend auf dem Registrierungsnamen (z. B. contosoacrregistry.azurecr.io). Diese Option enthält keinen DNL-Schutz.
TenantReuse: Fügt einen eindeutigen Hash basierend auf dem Mandanten- und Registrierungsnamen an, um sicherzustellen, dass der DNS-Name innerhalb des Mandanten eindeutig ist.
SubscriptionReuse: Fügt einen eindeutigen Hash basierend auf dem Abonnement, Mandanten und Registrierungsnamen an, um sicherzustellen, dass der DNS-Name innerhalb des Abonnements eindeutig ist.
ResourceGroupReuse: Fügt einen eindeutigen Hash basierend auf der Ressourcengruppe, dem Abonnement, dem Mandanten und dem Registrierungsnamen an, und stellt sicher, dass der DNS-Name innerhalb der Ressourcengruppe eindeutig ist.
NoReuse: Generiert einen eindeutigen DNS-Namen mit einem eindeutigen Hash jedes Mal, wenn die Registrierung erstellt wird, unabhängig von anderen Faktoren, um sicherzustellen, dass der DNS-Name immer eindeutig ist.

Hinweis

Unveränderliche Konfiguration: Der während der Registrierungserstellung ausgewählte DNL-Bereich ist dauerhaft und kann später nicht geändert werden. Dadurch wird ein konsistentes DNS-Verhalten gewährleistet und Unterbrechungen bei nachgeschalteten Verweisen verhindert.

DNS-Namensauswirkungen von DNL-Optionen

DNS-Namensformat: Für alle DNL-fähigen Optionen mit Ausnahme Unsecuredes DNS-Namens folgt das Format registryname-hash.azurecr.io, wobei der Gedankenstrich (-) als Hashdelineator dient. Um Konflikte zu vermeiden, ist Bindestrich (-) im Registrierungsnamen nicht zulässig. Beispielsweise hat eine Registrierung, die mit dem contosoacrregistry DNL-Bereich benannt TenantReuse ist, einen DNS-Namen wie contosoacrregistry-e7ggejfuhzhgedc8.azurecr.io.

Nachgeschaltete Verweise: Der DNS-Name kann sich vom Registrierungsnamen unterscheiden, sodass Aktualisierungen in nachgeschalteten Dateien wie Dockerfiles, Kubernetes YAML und Helm-Diagrammen erforderlich sind, um den vollständigen DNS-Namen mit dem DNL-Hash widerzuspiegeln. Wenn Ihre nachgelagerte Dockerfile-Datei beispielsweise auf eine Registrierung mit dem Namen contosoacrregistry mit dem DNL-Bereich TenantReuse verweisen soll, müssen Sie den Verweis auf contosoacrregistry-e7ggejfuhzhgedc8.azurecr.io in Ihrer nachgelagerten Dockerfile-Datei aktualisieren.

Konfigurieren des Rollenzuweisungsberechtigungsmodus

Optional können Sie den --role-assignment-mode Parameter verwenden, um den Rollenzuweisungsmodus der Registrierung anzugeben. Diese Option bestimmt, wie die Microsoft Entra-Rollenbasierte Zugriffssteuerung (RBAC) und die Rollenzuweisungen für das Register verwaltet werden, einschließlich der Nutzung von Microsoft Entra-Attributbasierter Zugriffssteuerung (ABAC) für Microsoft Entra-Repository-Berechtigungen.

Geben Sie rbac-abac an, dass für diesen Parameter standardmäßige Microsoft Entra RBAC-Rollenzuweisungen beibehalten werden sollen, während optional Microsoft Entra ABAC-Bedingungen für eine differenzierte Zugriffssteuerung auf Repositoryebene angewendet werden.

Weitere Informationen zu dieser Option finden Sie unter Microsoft Entra-attributbasierte Zugriffssteuerung (ABAC) für Repositoryberechtigungen.

Erstellen einer Containerregistrierung

az acr create --resource-group myResourceGroup \
  --name mycontainerregistry --sku Standard \
  --role-assignment-mode 'rbac-abac' \
  --dnl-scope TenantReuse

Wenn die Registrierung erstellt wird, sieht die Ausgabe etwa wie folgt aus:

{
  "adminUserEnabled": false,
  "creationDate": "2019-01-08T22:32:13.175925+00:00",
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroup/providers/Microsoft.ContainerRegistry/registries/mycontainerregistry",
  "location": "eastus",
  "loginServer": "mycontainerregistry-e7ggejfuhzhgedc8.azurecr.io",
  "name": "mycontainerregistry",
  "provisioningState": "Succeeded",
  "resourceGroup": "myResourceGroup",
  "sku": {
    "name": "Standard",
    "tier": "Standard"
  },
  "status": null,
  "storageAccount": null,
  "tags": {},
  "type": "Microsoft.ContainerRegistry/registries",
  "roleAssignmentMode": "AbacRepositoryPermissions",
  "autoGeneratedDomainNameLabelScope": "TenantReuse"
}

Beachten Sie loginServer in der Ausgabe. Dabei handelt es sich um den vollqualifizierten Registrierungsnamen (nur Kleinbuchstaben). Für den restlichen Teil dieser Schnellstartanleitung wird <registry-name> als Platzhalter für den Namen der Containerregistrierung verwendet, und <login-server> ist ein Platzhalter für den Anmeldeservernamen der Registrierung.

Tipp

In dieser Schnellstartanleitung erstellen Sie eine Standardregistrierung , die für die meisten Azure Container Registry-Workflows ausreicht. Wählen Sie andere Ebenen für einen höheren Speicher- und Imagedurchsatz aus und nutzen Sie Funktionen wie die Verbindung über einen privaten Endpunkt. Ausführliche Informationen zu verfügbaren Dienstebenen (SKUs) finden Sie unter Azure Container Registry-Tarife.

Anmelden bei der Registrierung

Bevor Sie Push- und Pullvorgänge für Containerimages ausführen können, müssen Sie sich bei der Registrierung anmelden. Verwenden Sie hierzu den Befehl az acr login. Geben Sie beim Anmelden bei der Azure CLI nur den Namen der Registrierungsressource an. Verwenden Sie nicht den vollqualifizierten Namen des Anmeldeservers.

az acr login --name <registry-name>

Beispiel:

az acr login --name mycontainerregistry

Der Befehl gibt nach Abschluss die Meldung Login Succeeded zurück.

Pushen eines Image in die Registrierung

Um ein Image mithilfe von Push an Ihre Azure Container Registry-Instanz übertragen zu können, benötigen Sie zunächst ein Image. Wenn Sie noch nicht über lokale Containerimages verfügen, führen Sie den folgenden docker pull-Befehl aus, um ein vorhandenes öffentliches Image abzurufen. In diesem Beispiel wird das Image hello-world aus Microsoft Container Registry gepullt.

docker pull mcr.microsoft.com/hello-world

Bevor Sie ein Image an Ihre Registrierung übertragen können, müssen Sie es mit dem Docker-Tag mit dem vollqualifizierten Namen Ihres Registrierungsanmeldungsservers markieren.

Das Format des Anmeldeservernamens für geschützte Registrierungen mit DNL, einschließlich eines eindeutigen DNS-Namenshashes, ist mycontainerregistry-abc123.azurecr.io.
Das Namensformat des Anmeldeservers für Registrierungen, die mit der Unsecure DNL-Option erstellt wurden, lautet mycontainerregistry.azurecr.io.

Wenn Ihre Registrierung beispielsweise mit dem Tenant Reuse DNL-Bereich erstellt wurde, sieht der Anmeldeserver möglicherweise so aus: mycontainerregistry-abc123.azurecr.io mit einem Hash im DNS-Namen. Wenn Ihre Registrierung mit der Unsecure DNL-Option erstellt wurde, würde der Anmeldeserver mycontainerregistry.azurecr.io ohne den Hash aussehen.

Weitere Informationen zu DNL-Optionen während der Registrierungserstellung und DNS-Namensauswirkungen finden Sie unter "Schnellstart – Registrierung im Portal erstellen".

Beispiel: Markieren eines Bilds vor dem Push

Markieren Sie das Image mit dem docker tag-Befehl unter Verwendung des Anmeldeservers Ihres Registries.

Taggingbild für eine Nicht-DNL-Registrierung:

docker tag mcr.microsoft.com/hello-world mycontainerregistry.azurecr.io/hello-world:v1

Taggingbild für eine DNL-aktivierte Registrierung:

docker tag mcr.microsoft.com/hello-world mycontainerregistry-abc123.azurecr.io/hello-world:v1

Nun können Sie das Image mit docker push per Pushvorgang an die Registrierungsinstanz übertragen. Ersetzen Sie <login-server> durch den Anmeldeservernamen Ihrer Registrierungsinstanz. In diesem Beispiel wird das Repository hello-world mit dem Image hello-world:v1 erstellt.

docker push <login-server>/hello-world:v1

Nachdem das Image in Ihre Containerregistrierung gepusht wurde, entfernen Sie das Image hello-world:v1 aus Ihrer lokalen Docker-Umgebung. (Beachten Sie, dass dieser Docker rmi-Befehl das Image nicht aus dem Hello-World-Repository in Ihrer Azure-Containerregistrierung entfernt.)

docker rmi <login-server>/hello-world:v1

Auflisten von Containerimages

Im folgenden Beispiel werden die Repositorys in Ihrer Registrierung aufgelistet:

az acr repository list --name <registry-name> --output table

Ausgabe:

Result
----------------
hello-world

Das folgende Beispiel listet die Tags des Repositorys hello-world auf.

az acr repository show-tags --name <registry-name> --repository hello-world --output table

Ausgabe:

Result
--------
v1

Ausführen des Images aus der Registrierung

Als Nächstes können Sie das Containerimage hello-world:v1 per Pull abrufen und mithilfe von docker run aus Ihrer Containerregistrierung ausführen:

docker run <login-server>/hello-world:v1

Beispielausgabe:

Unable to find image 'mycontainerregistry.azurecr.io/hello-world:v1' locally
v1: Pulling from hello-world
Digest: sha256:662dd8e65ef7ccf13f417962c2f77567d3b132f12c95909de6c85ac3c326a345
Status: Downloaded newer image for mycontainerregistry.azurecr.io/hello-world:v1

Hello from Docker!
This message shows that your installation appears to be working correctly.

[...]

Bereinigen von Ressourcen

Wenn Sie die Ressourcengruppe, die Containerregistrierung und die darin gespeicherten Containerimages nicht mehr benötigen, können Sie sie mit dem Befehl az group delete entfernen.

az group delete --name myResourceGroup

Nächste Schritte

In dieser Schnellstartanleitung haben Sie mit der Azure CLI eine Azure Container Registry-Instanz erstellt, ein Containerimage per Push an die Registrierung übertragen und das Image per Pull aus der Registrierung abgerufen und ausgeführt. Fahren Sie mit den Azure Container Registry-Tutorials fort, um eingehendere Informationen zu ACR zu erhalten.

Tutorials zu Azure Container Registry

Tutorials zu Azure Container Registry Tasks

Freigeben über