使用 Az CLI 进行 ACR 传输

项目
12/25/2023

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

满足先决条件

在尝试本文中的操作之前，请完成此处所述的先决条件。这意味着：

在两个云中都有一个现有的高级 SKU 注册表。
在两个云中都有一个现有的存储帐户容器。
在两个云中都有一个现有的密钥保管库，其中包含具有必要权限的有效 SAS 令牌。
在两个云中都安装了最新版本的 Az CLI。

安装 Az CLI 扩展

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

az extension add --name acrtransfer

在 AzureCloud 和其他云中，可以直接从公共存储帐户容器安装 Blob。 Blob 托管在 acrtransferext 存储帐户、dist 容器、acrtransfer-1.0.0-py2.py3-none-any.wh Blob 中。可能需要根据所在的云更改存储 URI 后缀。以下内容将在 AzureCloud 中安装：

az extension add --source https://acrtransferext.blob.core.windows.net/dist/acrtransfer-1.0.0-py2.py3-none-any.whl

使用 acrtransfer Az CLI 扩展创建 ExportPipeline

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

创建不含选项和系统分配标识的导出管道：

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

创建含所有可能选项和用户分配标识的导出管道：

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 \
--options OverwriteBlobs ContinueOnErrors \
--assign-identity /subscriptions/$MySubID/resourceGroups/$MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$MyIdentity

导出选项

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

参数	Value
options	OverwriteBlobs - 覆盖现有目标 blob ContinueOnErrors - 如果一个项目导出失败，则在源注册表中继续导出其余项目。

向 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。

创建不含选项和系统分配标识的导入管道：

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

创建包含一个导入管道，其中包含所有可能的选项和一个用户分配标识，并禁用源触发器：

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 \
--options DeleteSourceBlobOnSuccess OverwriteTags ContinueOnErrors \
--assign-identity /subscriptions/$MySubID/resourceGroups/$MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$MyIdentity \
--source-trigger-enabled False

导入选项

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

参数	Value
options	OverwriteTags - 覆盖现有目标标记 DeleteSourceBlobOnSuccess - 成功导入到目标注册表后删除源存储 blob ContinueOnErrors - 如果一个项目导入失败，则在目标注册表中继续导入其余项目。

向 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 标志。

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

az storage blob list --account-name $MyStorageAccount --container $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

注意

源触发器将仅导入上次修改时间为过去 60 天内的 Blob。如果打算使用源触发器导入早于该时间的 blob，请通过将 blob 元数据添加到 blob 来刷新 blob 的上次修改时间，或者使用手动创建的管道运行导入它们。

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

通过 acrtransfer Az 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

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

后续步骤

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

通过