ACR-Übertragung mit der Azure CLI

Mit ACR Transfer können Sie Containerimages und OCI-Artefakte zwischen Azure-Containerregistrierungen mithilfe eines zwischengeschalteten Speicherkontos übertragen, sodass sie ideal für Luftlücken- und cloudübergreifende Szenarien geeignet ist. Eine Übersicht über das Feature finden Sie unter Übertragen von Artefakten in eine andere Registrierung.

In diesem Artikel wird gezeigt, wie Sie die Funktion für die ACR-Übertragung mit der Azure CLI-Erweiterung „acrtransfer“ verwenden.

Erfüllen der Voraussetzungen

Bitte füllen Sie die in den Voraussetzungen für die ACR-Übertragung beschriebenen Voraussetzungen aus, bevor Sie die Aktionen in diesem Artikel versuchen. Dies bedeutet Folgendes:

• Sie verfügen über eine Premium-SKU-Registrierung in beiden Clouds.
• Sie besitzen einen Speicherkontocontainer in beiden Clouds.
• Stellen Sie bei Verwendung des SAS-Tokenspeicherzugriffsmodus sicher, dass Sie über einen vorhandenen Schlüsseltresor mit einem geheimen Schlüssel verfügen, der ein gültiges SAS-Token mit den erforderlichen Berechtigungen in beiden Clouds enthält.
• Wenn der Speicherzugriffsmodus für verwaltete Identitäten verwendet wird, vergewissern Sie sich, dass das verwaltete Identitätskonto der Pipeline über die entsprechende RBAC-Rolle (z.B. Storage Blob Data Contributor) für das Speicherkonto verfügt.
• In beiden Clouds ist eine aktuelle Version der Azure CLI installiert.

ACR-Übertragung unterstützt zwei Speicherzugriffsmodi: SAS-Token und verwaltete Identität. Sie müssen angeben, welcher Modus beim Erstellen von Pipelines über den --storage-access-mode Parameter verwendet werden soll. Einen detaillierten Vergleich finden Sie unter Speicherzugriffsmodi.

Installieren der Azure CLI-Erweiterung

In AzureCloud können Sie die Erweiterung mit dem folgenden Befehl installieren:

az extension add --name acrtransfer

Erstellen einer ExportPipeline-Ressource mit der Azure CLI-Erweiterung „acrtransfer“

Erstellen Sie mithilfe der Azure CLI-Erweiterung „acrtransfer“ eine ExportPipeline-Ressource für Ihre AzureCloud-Containerregistrierung.

SAS-Tokenmodus

Erstellen Sie eine Exportpipeline mit dem SAS-Tokenspeicher-Zugriffsmodus ohne Optionen und einer vom System zugewiesenen Identität:

az acr export-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--secret-uri https://$MyKV.vault.azure.net/secrets/$MySecret \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--storage-access-mode SasToken

Erstellen Sie eine Exportpipeline mit dem SAS-Tokenmodus, allen möglichen Optionen und einer vom Benutzer zugewiesenen Identität:

az acr export-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--secret-uri https://$MyKV.vault.azure.net/secrets/$MySecret \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--storage-access-mode SasToken \
--options OverwriteBlobs ContinueOnErrors \
--assign-identity /subscriptions/$MySubID/resourceGroups/$MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$MyIdentity

Verwalteter Identitätsmodus

Bei Verwendung des Speicherzugriffsmodus Verwaltete Identität authentifiziert sich die Pipeline unter Verwendung der verwalteten Entra-Identität der Pipeline direkt beim Speicherkonto. Für den Speicherzugriff ist kein Key Vault- oder SAS-Token erforderlich.

Erstellen Sie eine Exportpipeline mit dem Modus "Verwaltete Identität" und einer vom System zugewiesenen Identität:

az acr export-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--storage-access-mode ManagedIdentity

Erstellen Sie eine Exportpipeline mit dem Modus "Verwaltete Identität", alle möglichen Optionen und eine vom Benutzer zugewiesene Identität:

az acr export-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--storage-access-mode ManagedIdentity \
--options OverwriteBlobs ContinueOnErrors \
--assign-identity /subscriptions/$MySubID/resourceGroups/$MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$MyIdentity

Exportoptionen

Die options-Eigenschaft für die Exportpipelines unterstützt optionale boolesche Werte. Die folgenden Werte werden empfohlen:

Erteilen von keyvault-Richtlinienzugriff für die ExportPipeline-Identität

Wenn Sie Ihre Pipeline mit einer benutzerseitig zugewiesenen Identität erstellt haben, erteilen Sie dieser benutzerseitig zugewiesenen Identität einfach Zugriffsrichtlinienberechtigungen vom Typ secret get für den Schlüsseltresor.

Wenn Sie Ihre Pipeline mit einer vom System zugewiesenen Identität erstellt haben, müssen Sie zuerst die Prinzipal-ID abrufen, die das System Ihrer Pipelineressource zugewiesen hat.

Führen Sie den folgenden Befehl aus, um Ihre Pipelineressource abzurufen:

az acr export-pipeline show --resource-group $MyRG --registry $MyReg --name $MyPipeline

Aus dieser Ausgabe möchten Sie den Wert im principalId Feld kopieren.

Anschließend werden Sie den folgenden Befehl ausführen, um diesem Prinzipal die entsprechenden Zugriffsrichtlinienberechtigungen vom Typ secret get für Ihren Schlüsseltresor zu erteilen.

az keyvault set-policy --name $MyKeyvault --secret-permissions get --object-id $MyPrincipalID

Erstellen einer ImportPipeline-Ressource mit der Azure CLI-Erweiterung „acrtransfer“

Erstellen Sie mithilfe der Azure CLI-Erweiterung „acrtransfer“ eine ImportPipeline-Ressource in Ihrer Zielcontainerregistrierung. In der Pipeline ist standardmäßig aktiviert, dass automatisch eine Import PipelineRun-Ressource erstellt wird, wenn der angefügte Speicherkontocontainer ein neues Artefaktblob empfängt.

SAS-Tokenmodus

Erstellen Sie eine Importpipeline mit dem SAS-Token-Speicherzugriffsmodus, ohne Optionen und einer vom System zugewiesenen Identität.

az acr import-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--secret-uri https://$MyKV.vault.azure.net/secrets/$MySecret \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--storage-access-mode SasToken

Erstellen Sie eine Importpipeline mit dem SAS-Token-Modus, mit allen möglichen Optionen, deaktiviertem Quell-Trigger und mit einer vom Benutzer zugewiesenen Identität.

az acr import-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--secret-uri https://$MyKV.vault.azure.net/secrets/$MySecret \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--storage-access-mode SasToken \
--options DeleteSourceBlobOnSuccess OverwriteTags ContinueOnErrors \
--assign-identity /subscriptions/$MySubID/resourceGroups/$MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$MyIdentity \
--source-trigger-enabled False

Verwalteter Identitätsmodus

Bei Verwendung des Speicherzugriffsmodus Verwaltete Identität authentifiziert sich die Pipeline unter Verwendung der verwalteten Entra-Identität der Pipeline direkt beim Speicherkonto. Für den Speicherzugriff ist kein Key Vault- oder SAS-Token erforderlich.

Erstellen Sie eine Importpipeline mit dem Modus "Verwaltete Identität" und einer vom System zugewiesenen Identität:

az acr import-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--storage-access-mode ManagedIdentity

Erstellen Sie eine Importpipeline mit dem Modus "Verwaltete Identität", alle möglichen Optionen, deaktivierten Quelltrigger und eine vom Benutzer zugewiesene Identität:

az acr import-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--storage-container-uri https://$MyStorage.blob.core.windows.net/$MyContainer \
--storage-access-mode ManagedIdentity \
--options DeleteSourceBlobOnSuccess OverwriteTags ContinueOnErrors \
--assign-identity /subscriptions/$MySubID/resourceGroups/$MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$MyIdentity \
--source-trigger-enabled False

Importieren von Optionen

Die options-Eigenschaft für die Importpipeline unterstützt optionale boolesche Werte. Die folgenden Werte werden empfohlen:

Erteilen von keyvault-Richtlinienzugriff für die ImportPipeline-Identität

Wenn Sie Ihre Pipeline mit einer benutzerseitig zugewiesenen Identität erstellt haben, erteilen Sie dieser benutzerseitig zugewiesenen Identität einfach Zugriffsrichtlinienberechtigungen vom Typ secret get für den Schlüsseltresor.

Wenn Sie Ihre Pipeline mit einer vom System zugewiesenen Identität erstellt haben, müssen Sie zuerst die Prinzipal-ID abrufen, die das System Ihrer Pipelineressource zugewiesen hat.

Führen Sie den folgenden Befehl aus, um Ihre Pipelineressource abzurufen:

az acr import-pipeline show --resource-group $MyRG --registry $MyReg --name $MyPipeline

Aus dieser Ausgabe möchten Sie den Wert im principalId Feld kopieren.

Anschließend werden Sie den folgenden Befehl ausführen, um diesem Prinzipal die entsprechende Zugriffsrichtlinie vom Typ secret get für Ihren Schlüsseltresor zuzuweisen.

az keyvault set-policy --name $MyKeyvault --secret-permissions get --object-id $MyPrincipalID

Erstellen einer PipelineRun-Ressource für den Export mit der Azure CLI-Erweiterung „acrtransfer“

Erstellen Sie mithilfe der Azure CLI-Erweiterung „acrtransfer“ eine PipelineRun-Ressource für Ihre Containerregistrierung. Diese Ressource führt die zuvor von Ihnen erstellte ExportPipeline-Ressource aus und exportiert angegebene Artefakte als Blob aus Ihrer Containerregistrierung in Ihren Speicherkontocontainer.

Erstellen Sie eine Exportpipelineausführung:

az acr pipeline-run create \
--resource-group $MyRG \
--registry $MyReg \
--pipeline $MyPipeline \
--name $MyPipelineRun \
--pipeline-type export \
--storage-blob $MyBlob \
--artifacts hello-world:latest hello-world@sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042 \
--force-redeploy

Wenn Sie eine PipelineRun-Ressource mit identischen Eigenschaften erneut bereitstellen, müssen Sie das Flag „--force-redeploy“ verwenden.

Authentifizierungsprotokollierung für Pipelineausführungen

Wenn eine Pipeline ausgeführt wird, zeigt die CLI eine Protokollmeldung an, die angibt, welche Authentifizierungsmethode für den Zugriff auf das Speicherkonto verwendet wird. Dadurch wird sichergestellt, ob die Pipeline verwaltete Identität oder SAS-Tokenauthentifizierung verwendet:

Authenticating to Storage Account using Entra Managed Identity.

oder

Authenticating to Storage Account using Storage SAS Token.

Es kann einige Minuten dauern, bis Artefakte exportiert werden. Wenn die Bereitstellung erfolgreich abgeschlossen wurde, überprüfen Sie den Artefaktexport, indem Sie das exportierte Blob im Container des Quellspeicherkontos auflisten. Führen Sie z. B. den Befehl az storage blob list Befehl aus:

az storage blob list --account-name $MyStorageAccount --container-name $MyContainer --output table

Domänenübergreifendes Übertragen eines Blobs

In den meisten Anwendungsfällen verwenden Sie jetzt eine domänenübergreifende Lösung oder eine andere Methode, um Ihr BLOB aus dem Speicherkonto in Ihrer Quelldomäne (dem Speicherkonto, das Ihrer Exportpipeline zugeordnet ist) in das Speicherkonto in Ihrer Zieldomäne (das Speicherkonto, das Ihrer Importpipeline zugeordnet ist) zu übertragen. An diesem Punkt wird davon ausgegangen, dass das Blob im Zieldomänenspeicherkonto eingegangen ist, das Ihrer Importpipeline zugeordnet ist.

Auslösen der ImportPipeline-Ressource

Wenn Sie den --source-trigger-enabled False Parameter beim Erstellen der Importpipeline nicht verwendet haben, wird die Pipeline innerhalb von 15 Minuten ausgelöst, nachdem das BLOB im Container des Speicherkontos eingetroffen ist. Es kann einige Minuten dauern, bis Artefakte importiert werden. Wenn der Import erfolgreich abgeschlossen ist, überprüfen Sie den Artefaktimport, indem Sie die Tags des Repositories auflisten, das Sie in die Zielcontainerregistrierung importieren. Führen Sie z. B. az acr repository show-tags aus:

az acr repository show-tags --name $MyRegistry --repository $MyRepository

Wenn Sie den --source-trigger-enabled False Parameter beim Erstellen Ihrer ImportPipeline verwendet haben, müssen Sie einen PipelineRun manuell erstellen, wie im folgenden Abschnitt gezeigt.

Erstellen von PipelineRun für den Import mit der Azure CLI-Erweiterung „acrtransfer“

Erstellen Sie mithilfe der Azure CLI-Erweiterung „acrtransfer“ eine PipelineRun-Ressource für Ihre Containerregistrierung. Diese Ressource führt die zuvor erstellte ImportPipeline-Ressource aus und importiert angegebene Blobs aus Ihrem Speicherkonto in Ihre Containerregistrierung.

Erstellen Sie eine Importpipelineausführung:

az acr pipeline-run create \
--resource-group $MyRG \
--registry $MyReg \
--pipeline $MyPipeline \
--name $MyPipelineRun \
--pipeline-type import \
--storage-blob $MyBlob \
--force-redeploy

Wenn Sie eine PipelineRun-Ressource mit identischen Eigenschaften erneut bereitstellen, müssen Sie das Flag „--force-redeploy“ verwenden.

Es kann einige Minuten dauern, bis Artefakte importiert werden. Wenn der Import erfolgreich abgeschlossen wurde, überprüfen Sie den Artefaktimport, indem Sie die Repositorys in der Zielcontainerregistrierung auflisten. Führen Sie z. B. az acr repository show-tags aus:

az acr repository show-tags --name $MyRegistry --repository $MyRepository

Löschen von ACR-Übertragungsressourcen

Löschen Sie eine ExportPipeline-Ressource:

az acr export-pipeline delete --resource-group $MyRG --registry $MyReg --name $MyPipeline

Löschen Sie eine ImportPipeline-Ressource:

az acr import-pipeline delete --resource-group $MyRG --registry $MyReg --name $MyPipeline

Löschen Sie eine PipelineRun-Ressource. Beachten Sie, dass dadurch die vom PipelineRun ausgeführte Aktion nicht rückgängig gemacht wird. Dies entspricht eher dem Löschen des Protokolls von PipelineRun.

az acr pipeline-run delete --resource-group $MyRG --registry $MyReg --name $MyPipelineRun

Problembehandlung für die ACR-Übertragung

Informationen zur Problembehandlung finden Sie unter Problembehandlung für die ACR-Übertragung.

Nächste Schritte

• Erfahren Sie, wie Sie die Erstellung von Exportpipelines aus einer netzwerkbeschränkten Containerregistrierung blockieren.