使用 Az CLI 进行 ACR 传输

使用 ACR 转移，可以使用中间存储帐户在 Azure 容器注册表之间传输容器映像和 OCI 项目，非常适合用于隔离网络和跨云场景。 有关功能的概述，请参阅 将项目传输到另一个注册表。

本文介绍如何通过 acrtransfer Az CLI 扩展使用 ACR 传输功能。

满足先决条件

在尝试本文中的作之前，请先完成 ACR 传输先决条件 中概述的先决条件。 这意味着：

• 在两个云中都有一个现有的高级 SKU 注册表。
• 您在两个云服务提供商中都有一个现有的存储帐户容器。
• 如果使用 SAS 令牌存储访问模式，请确保您现有的密钥保管库中存有一个机密，机密包含一个有效的 SAS 令牌，并在两个云中具有必要的权限。
• 如果使用 托管标识 存储访问模式，请确保管道的托管标识在存储帐户上具有适当的 RBAC 角色（例如 Storage Blob Data Contributor）。
• 在两个云中都安装了最新版本的 Az CLI。

ACR 传输支持两种存储访问模式： SAS 令牌 和 托管标识。 创建管道时，必须指定要通过 --storage-access-mode 参数使用的模式。 有关详细比较，请参阅 存储访问模式。

安装 Az CLI 扩展

在 AzureCloud 中，可以通过以下命令安装扩展：

az extension add --name acrtransfer

使用 acrtransfer Az CLI 扩展创建 ExportPipeline

使用 acrtransfer Az CLI 扩展为 AzureCloud 容器注册表创建 ExportPipeline 资源。

SAS 令牌模式

使用 SAS 令牌存储访问模式、无选项和系统分配的标识创建导出管道：

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

使用 SAS 令牌模式、所有可能的选项和用户分配的标识创建导出管道：

az acr export-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--secret-uri https://$MyKV.vault.azure.cn/secrets/$MySecret \
--storage-container-uri https://$MyStorage.blob.core.chinacloudapi.cn/$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.chinacloudapi.cn/$MyContainer \
--storage-access-mode ManagedIdentity

使用托管标识模式、所有可能的选项和用户分配的标识创建导出管道：

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

导出选项

导出管道的 options 属性支持可选的布尔值。 建议使用以下值：

向 ExportPipeline 身份授予密钥库策略访问权限

如果创建了含用户分配标识的管道，只需向此用户分配的标识授予对密钥保管库的 secret get 访问策略权限。

如果创建了含系统分配标识的管道，则首先需要检索系统已分配给管道资源的 principalId。

运行以下命令以检索管道资源：

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

使用 acrtransfer Az CLI 扩展创建 ImportPipeline

使用 acrtransfer Az CLI 扩展在目标容器注册表中创建 ImportPipeline 资源。 默认情况下，当附加的存储帐户容器接收到新的项目 Blob 时，管道会自动创建一个 Import PipelineRun。

SAS 令牌模式

使用 SAS 令牌存储访问模式、无选项和系统分配的标识创建导入管道：

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

创建具有 SAS 令牌模式、所有可能选项、已禁用源触发器和用户分配标识的导入管道：

az acr import-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--secret-uri https://$MyKV.vault.azure.cn/secrets/$MySecret \
--storage-container-uri https://$MyStorage.blob.core.chinacloudapi.cn/$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.chinacloudapi.cn/$MyContainer \
--storage-access-mode ManagedIdentity

使用托管身份模式、所有可能的选项、禁用的源触发器以及用户分配的身份来创建导入管道：

az acr import-pipeline create \
--resource-group $MyRG \
--registry $MyReg \
--name $MyPipeline \
--storage-container-uri https://$MyStorage.blob.core.chinacloudapi.cn/$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 标识

如果创建了含用户分配标识的管道，只需向此用户分配的标识授予对密钥保管库的 secret get 访问策略权限。

如果创建了含系统分配标识的管道，则首先需要检索系统已分配给管道资源的 principalId。

运行以下命令以检索管道资源：

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

通过 acrtransfer Az CLI 扩展为导出创建 PipelineRun

使用 acrtransfer Az CLI 扩展为容器注册表创建 PipelineRun 资源。 此资源运行之前创建的 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.

导出制品可能需要几分钟。 在部署成功完成后，请通过在源存储帐户的容器中列出导出的 Blob 来验证工件导出。 例如，运行 az storage blob list 命令：

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

在不同域之间传输 Blob 数据

在大多数情况下，现在将使用跨域解决方案或其他方法将 Blob 从源域中的存储帐户（与导出管道关联的存储帐户）传输到目标域中的存储帐户（与导入管道关联的存储帐户）。 此时，我们将假定 Blob 已到达与导入管道关联的目标域存储帐户。

触发 ImportPipeline 资源

如果在创建导入管道时未使用 --source-trigger-enabled False 参数，则 Blob 到达存储帐户容器后 15 分钟内将触发管道。 导入构建物可能需要几分钟。 导入成功完成后，通过在目标容器注册表中列出要导入的存储库上的标记来验证项目导入。 例如，运行 az acr repository show-tags：

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

如果在创建 ImportPipeline 时确实使用了 --source-trigger-enabled False 该参数，则需要手动创建 PipelineRun，如以下部分所示。

通过 az acrtransfer CLI 扩展插件为导入创建 PipelineRun

使用 acrtransfer Az CLI 扩展为容器注册表创建 PipelineRun 资源。 此资源运行之前创建的 ImportPipeline 资源，并将指定的 Blob 从存储帐户导入到容器注册表中。

创建导入管道运行实例：

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

删除导入管道：

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 传输故障排除以获取故障排除指南。

后续步骤

• 了解如何从受网络限制的容器注册表中阻止创建导出管道。