Передача ACR с помощью Az CLI

Передача ACR позволяет переносить образы контейнеров и артефакты OCI между реестрами контейнеров Azure, используя промежуточную учетную запись хранения, что делает её идеальной для изолированных и кросс-облачных сценариев. Общие сведения о функции см. в разделе "Передача артефактов в другой реестр".

В этой статье показано, как использовать функцию передачи ACR с расширением acrtransfer Az CLI.

Завершите выполнение предварительных условий

Выполните предварительные требования, описанные в предварительных требованиях для передачи ACR , прежде чем пытаться выполнить действия в этой статье. Это означает, что:

• У вас есть существующий реестр SKU "Премиум" в обоих облаках.
• У вас есть контейнер учетной записи хранения в обоих облаках.
• Если используется режим доступа к хранилищу маркеров SAS , убедитесь, что у вас есть хранилище ключей с секретом, содержащим допустимый маркер SAS с необходимыми разрешениями в обоих облаках.
• При использовании режима доступа к хранилищу управляемых удостоверений убедитесь, что управляемое удостоверение конвейера имеет соответствующую роль RBAC (например Storage Blob Data Contributor, ) в учетной записи хранения.
• У вас есть последняя версия Az CLI, установленная в обоих облаках.

Передача ACR поддерживает два режима доступа к хранилищу: токен SAS и управляемая идентификация. При создании конвейеров необходимо указать, какой режим использовать, через параметр --storage-access-mode. Подробное сравнение см. в разделе "Режимы доступа к хранилищу".

Установка расширения Az CLI

В AzureCloud можно установить расширение с помощью следующей команды:

az extension add --name acrtransfer

Создание ExportPipeline с расширением acrtransfer Az CLI

Создайте ресурс ExportPipeline для реестра контейнеров AzureCloud с помощью расширения acrtransfer Az CLI.

Режим токена SAS

Создайте конвейер экспорта с режимом доступа к хранилищу маркеров SAS, без параметров и удостоверения, назначаемого системой:

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

Создайте конвейер экспорта в режиме токена SAS, со всеми возможными параметрами и пользовательской назначенной идентичностью:

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

Режим управляемого удостоверения

При использовании режима доступа к хранилищу управляемого идентификатора конвейер аутентифицируется непосредственно в учетной записи хранения с помощью управляемого идентификатора Entra, связанного с конвейером. Для доступа к хранилищу не требуется маркер Key Vault или SAS.

Создайте конвейер экспорта с режимом управляемого удостоверения и удостоверением, назначаемое системой:

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

Создайте конвейер экспорта с режимом управляемого удостоверения, всеми возможными параметрами и удостоверением, назначенным пользователем:

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

Параметры экспорта

Свойство options для конвейеров экспорта поддерживает необязательные булевые значения. Рекомендуются следующие значения.

Предоставьте ExportPipeline доступ к политике keyvault

Если вы создали конвейер с назначаемым пользователем удостоверением, просто предоставьте этому удостоверению разрешения политики доступа в хранилище ключей secret get.

Если вы создали конвейер с удостоверением, назначаемым системой, вам сначала необходимо получить идентификатор объекта, который система назначила вашему ресурсу конвейера.

Выполните следующую команду, чтобы получить ресурс конвейера:

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

Из этого вывода необходимо скопировать значение из поля principalId.

Затем выполните следующую команду, чтобы предоставить этому субъекту соответствующие secret get разрешения политики доступа в ваше хранилище ключей.

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

Создайте ImportPipeline с использованием расширения acrtransfer Az CLI

Создайте ресурс ImportPipeline в целевом реестре контейнеров с помощью расширения acrtransfer Az CLI. По умолчанию конвейер настроен на автоматическое создание Import PipelineRun, когда контейнер в подключенной учетной записи хранилища получает новый blob артефакта.

Режим токена SAS

Создайте конвейер импорта с режимом доступа к хранилищу через токены SAS, без параметров и c системным назначенным удостоверением.

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

Создайте конвейер импорта в режиме токена SAS, используя все возможные параметры, с отключённым триггер-источником и назначаемым пользователем удостоверением.

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

Режим управляемого удостоверения

При использовании режима доступа к хранилищу Управляемая идентификация конвейер аутентифицируется напрямую в учетной записи хранения, используя управляемую идентификацию Entra для конвейера. Для доступа к хранилищу не требуется маркер Key Vault или SAS.

Создайте конвейер импорта с помощью режима управляемого удостоверения и назначаемого системой удостоверения:

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

Создайте конвейер импорта с режимом управляемого удостоверения, всеми возможными параметрами, отключенным источником триггера и удостоверением, назначенным пользователем:

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

Параметры импорта

Свойство options для конвейера импорта поддерживает дополнительные логические значения. Рекомендуются следующие значения.

Предоставьте идентификатору ImportPipeline доступ к политике Key Vault

Если вы создали конвейер с назначаемым пользователем удостоверением, просто предоставьте этому удостоверению разрешения политики доступа в хранилище ключей secret get.

Если вы создали конвейер с удостоверением, назначаемым системой, вам сначала необходимо получить идентификатор объекта, который система назначила вашему ресурсу конвейера.

Выполните следующую команду, чтобы получить ресурс конвейера:

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

Из этого вывода необходимо скопировать значение из поля principalId.

Затем выполните следующую команду для предоставления этому субъекту соответствующей secret get политики доступа в хранилище ключей.

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

Создайте PipelineRun для экспорта с использованием расширения acrtransfer для az CLI.

Создайте ресурс PipelineRun для реестра контейнеров с помощью расширения acrtransfer Az CLI. Этот ресурс запускает ресурс ExportPipeline, созданный ранее, и экспортирует указанные артефакты из реестра контейнеров как BLOB в контейнер вашей учетной записи хранения.

Создание конвейера экспорта:

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

При повторном развертывании ресурса PipelineRun с идентичными свойствами необходимо использовать флаг --force-redeploy.

Ведение журнала проверки подлинности запуска конвейера

При запуске выполнения конвейера CLI (интерфейс командной строки) отображает лог-сообщение, указывающее, какой метод проверки подлинности используется для доступа к учетной записи хранения. Это помогает подтвердить, использует ли конвейер управляемое удостоверение или аутентификацию маркером SAS.

Authenticating to Storage Account using Entra Managed Identity.

или

Authenticating to Storage Account using Storage SAS Token.

Экспорт артефактов может занять несколько минут. После успешного завершения развертывания проверьте экспорт артефактов, убедившись, что экспортированный блоб присутствует в контейнере исходной учетной записи хранения. Например, выполните команду az storage blob list:

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

Передача BLOB между доменами

В большинстве случаев вы будете использовать решение для междоменного взаимодействия или другой метод для передачи вашего блоба из учетной записи хранения в исходном домене (учетная запись хранения, связанная с экспортным конвейером) в учетную запись хранения в целевом домене (учетная запись хранения, связанная с импортным конвейером). На этом этапе предполагается, что объект BLOB прибыл в целевую учетную запись хранилища в домене, связанную с импортной конвейерной линией.

Триггер ресурса ImportPipeline

Если вы не использовали параметр --source-trigger-enabled False при создании конвейера импорта, то конвейер запустится в течение 15 минут после поступления blob в контейнер учетной записи хранения. Импорт артефактов может занять несколько минут. После успешного завершения импорта проверьте импорт артефактов, перечислив теги в репозитории, который вы импортируете в целевом реестре контейнеров. Например, выполните az acr repository show-tags:

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

При использовании параметра --source-trigger-enabled False при создании ImportPipeline следует вручную создать PipelineRun, как показано в следующем разделе.

Создайте PipelineRun для импорта, используя расширение Azure CLI acrtransfer.

Создайте ресурс PipelineRun для реестра контейнеров с помощью расширения acrtransfer Az CLI. Этот ресурс запускает созданный вами ранее ресурс ImportPipeline и импортирует указанные блобы из вашей учетной записи хранения в реестр контейнеров.

Создайте конвейер импорта:

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

При повторном развертывании ресурса PipelineRun с идентичными свойствами необходимо использовать флаг --force-redeploy.

Импорт артефактов может занять несколько минут. После успешного завершения процесса проверьте, как прошел импорт артефактов. Для этого выведите список репозиториев в целевом реестре контейнеров. Например, выполните az acr repository show-tags:

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

Удалить ресурсы передачи ACR

Удаление ExportPipeline:

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

Удаление ImportPipeline:

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

Удаление ресурса PipelineRun. Обратите внимание, что это не отменяет действие, выполненное PipelineRun. Это больше похоже на удаление журнала PipelineRun.

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

Устранение неполадок при передаче ACR

Ознакомьтесь с руководством по устранению неполадок с ACR Transfer.

Дальнейшие шаги

• Узнайте, как заблокировать возможность создания конвейеров экспорта из ограниченного сетью реестра контейнеров.