使用 ARM 模板进行 ACR 传输

项目
10/28/2024

满足先决条件

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

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

重要

由于技术限制，ACR 传输支持层大小限制为 8GB 的项目。

请考虑使用 Az CLI 扩展

对于大多数非自动化用例，我们建议尽可能使用 Az CLI 扩展。可在此处查看 Az CLI 扩展的文档。

使用资源管理器创建 ExportPipeline

使用 Azure 资源管理器模板部署为源容器注册表创建 ExportPipeline 资源。

将 ExportPipeline 资源管理器模板文件复制到本地文件夹。

在文件 azuredeploy.parameters.json 中输入以下参数值：

参数	Value
registryName	源容器注册表的名称
exportPipelineName	为导出管道选择的名称
targetUri	源环境（导出管道的目标）中存储容器的 URI。示例： `https://sourcestorage.blob.core.chinacloudapi.cn/transfer`
KeyVaultName	源密钥保管库的名称
sasTokenSecretName	源密钥保管库中 SAS 令牌机密的名称示例：acrexportsas

导出选项

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

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

创建资源

运行 az deployment group create，以创建名为 exportPipeline 的资源，如以下示例所示。默认情况下，选择第一个选项时，示例模板将在 ExportPipeline 资源中启用系统分配的标识。

选择第二个选项时，可以为资源提供用户分配的标识。（未显示用户分配的标识的创建。）

无论选择哪个选项，模板都将配置标识，以访问导出密钥保管库中的 SAS 令牌。

选项 1：创建资源并启用系统分配的标识

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipeline \
  --parameters azuredeploy.parameters.json

选项 2：创建资源并提供用户分配的标识

在此命令中，输入用户分配的标识的资源 ID 作为附加参数。

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipeline \
  --parameters azuredeploy.parameters.json \
  --parameters userAssignedIdentity="/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myUserAssignedIdentity"

在命令输出中，记下管道的资源 ID (id)。可运行 az deployment group show 将此值存储在环境变量中供将来使用。例如：

EXPORT_RES_ID=$(az deployment group show \
  --resource-group $SOURCE_RG \
  --name exportPipeline \
  --query 'properties.outputResources[1].id' \
  --output tsv)

使用资源管理器创建 ImportPipeline

使用 Azure 资源管理器模板部署在目标容器注册表中创建 ImportPipeline 资源。默认情况下，当目标环境中的存储帐户具有项目 blob 时，管道会自动导入。

将 ImportPipeline 资源管理器模板文件复制到本地文件夹。

在文件 azuredeploy.parameters.json 中输入以下参数值：

参数	Value
registryName	目标容器注册表的名称
importPipelineName	为导入管道选择的名称
sourceUri	目标环境（导入管道的源）中存储容器的 URI。示例： `https://targetstorage.blob.core.chinacloudapi.cn/transfer`
KeyVaultName	目标密钥保管库的名称
sasTokenSecretName	目标密钥保管库中 SAS 令牌机密的名称示例：acr importsas

导入选项

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

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

创建资源

运行 az deployment group create，以创建名为 importPipeline 的资源，如以下示例所示。默认情况下，选择第一个选项时，示例模板将在 ImportPipeline 资源中启用系统分配的标识。

选择第二个选项时，可以为资源提供用户分配的标识。（未显示用户分配的标识的创建。）

无论选择哪个选项，模板都将配置标识，以访问导入密钥保管库中的 SAS 令牌。

选项 1：创建资源并启用系统分配的标识

az deployment group create \
  --resource-group $TARGET_RG \
  --template-file azuredeploy.json \
  --name importPipeline \
  --parameters azuredeploy.parameters.json

选项 2：创建资源并提供用户分配的标识

在此命令中，输入用户分配的标识的资源 ID 作为附加参数。

az deployment group create \
  --resource-group $TARGET_RG \
  --template-file azuredeploy.json \
  --name importPipeline \
  --parameters azuredeploy.parameters.json \
  --parameters userAssignedIdentity="/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myUserAssignedIdentity"

如果计划手动运行导入，请记下管道的资源 ID (id)。可运行 az deployment group show 命令将此值存储在环境变量中供将来使用。例如：

IMPORT_RES_ID=$(az deployment group show \
  --resource-group $TARGET_RG \
  --name importPipeline \
  --query 'properties.outputResources[1].id' \
  --output tsv)

使用资源管理器创建用于导出的 PipelineRun

使用 Azure 资源管理器模板部署为源容器注册表创建 PipelineRun 资源。此资源运行之前创建的 ExportPipeline 资源，并将容器注册表中的指定项目作为 blob 导出到源存储帐户。

将 PipelineRun 资源管理器模板文件复制到本地文件夹。

在文件 azuredeploy.parameters.json 中输入以下参数值：

参数	Value
registryName	源容器注册表的名称
pipelineRunName	为运行选择的名称
pipelineResourceId	导出管道的资源 ID。示例： `/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerRegistry/registries/<sourceRegistryName>/exportPipelines/myExportPipeline`
targetName	为导出到源存储帐户的项目 blob 选择的名称，如 myblob
项目	要传输的源项目的数组，作为标记或清单摘要示例： `[samples/hello-world:v1", "samples/nginx:v1" , "myrepository@sha256:0a2e01852872..."]`

如果重新部署具有相同属性的 PipelineRun 资源，则还必须使用 forceUpdateTag 属性。

运行 az deployment group create 以创建 PipelineRun 资源。下面的示例将部署命名为 exportPipelineRun。

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipelineRun \
  --parameters azuredeploy.parameters.json

为供后续使用，请将管道运行的资源 ID 存储到环境变量中：

EXPORT_RUN_RES_ID=$(az deployment group show \
  --resource-group $SOURCE_RG \
  --name exportPipelineRun \
  --query 'properties.outputResources[0].id' \
  --output tsv)

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

az storage blob list \
  --account-name $SOURCE_SA \
  --container transfer \
  --output table

传输 blob（可选）

使用 AzCopy 工具或其他方法将 blob 数据从源存储帐户传输到目标存储帐户。

例如，以下 azcopy copy 命令会将源帐户下 transfer 容器中的 myblob 复制到目标帐户下的 transfer 容器。如果该 blob 存在于目标帐户中，则会被覆盖。身份验证使用对源和目标容器具有相应权限的 SAS 令牌。（未显示用于创建令牌的步骤。）

azcopy copy \
  'https://<source-storage-account-name>.blob.core.chinacloudapi.cn/transfer/myblob'$SOURCE_SAS \
  'https://<destination-storage-account-name>.blob.core.chinacloudapi.cn/transfer/myblob'$TARGET_SAS \
  --overwrite true

触发 ImportPipeline 资源

如果启用了 ImportPipeline 的 sourceTriggerStatus 参数（默认值），将 blob 复制到目标存储帐户后会触发管道。导入项目可能需要几分钟。导入成功完成后，请在目标容器注册表中列出存储库，以验证项目导入。例如，运行 az acr repository list：

az acr repository list --name <target-registry-name>

注意

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

如果未启用导入管道的 sourceTriggerStatus 参数，请手动运行 ImportPipeline 资源，如以下部分所示。

使用资源管理器创建用于导入的 PipelineRun（可选）

还可以使用 PipelineRun 资源触发用于目标容器注册表项目导入的 ImportPipeline。

将 PipelineRun 资源管理器模板文件复制到本地文件夹。

在文件 azuredeploy.parameters.json 中输入以下参数值：

参数	Value
registryName	目标容器注册表的名称
pipelineRunName	为运行选择的名称
pipelineResourceId	导入管道的资源 ID。示例： `/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerRegistry/registries/<sourceRegistryName>/importPipelines/myImportPipeline`
sourceName	存储帐户中已导出项目的现有 blob 名称，如 myblob

如果重新部署具有相同属性的 PipelineRun 资源，则还必须使用 forceUpdateTag 属性。

运行 az deployment group create 以运行资源。

az deployment group create \
  --resource-group $TARGET_RG \
  --name importPipelineRun \
  --template-file azuredeploy.json \
  --parameters azuredeploy.parameters.json

为供后续使用，请将管道运行的资源 ID 存储到环境变量中：

IMPORT_RUN_RES_ID=$(az deployment group show \
  --resource-group $TARGET_RG \
  --name importPipelineRun \
  --query 'properties.outputResources[0].id' \
  --output tsv)

部署成功完成后，请在目标容器注册表中列出存储库，以验证项目导入。例如，运行 az acr repository list：

az acr repository list --name <target-registry-name>

重新部署 PipelineRun 资源

如果重新部署具有相同属性的 PipelineRun 资源，则必须利用 forceUpdateTag 属性。此属性指示应重新创建 PipelineRun 资源，即使配置未更改也是如此。请确保 forceUpdateTag 在每次重新部署 PipelineRun 资源时都不同。下面的示例重新创建 PipelineRun 以用于导出。当前日期/时间用于设置 forceUpdateTag，从而确保此属性始终唯一。

CURRENT_DATETIME=`date +"%Y-%m-%d:%T"`

az deployment group create \
  --resource-group $SOURCE_RG \
  --template-file azuredeploy.json \
  --name exportPipelineRun \
  --parameters azuredeploy.parameters.json \
  --parameters forceUpdateTag=$CURRENT_DATETIME

删除管道资源

以下示例命令使用 az resource delete 删除本文中创建的管道资源。资源 ID 以前存储在环境变量中。

# Delete export resources
az resource delete \
--resource-group $SOURCE_RG \
--ids $EXPORT_RES_ID $EXPORT_RUN_RES_ID \
--api-version 2019-12-01-preview

# Delete import resources
az resource delete \
--resource-group $TARGET_RG \
--ids $IMPORT_RES_ID $IMPORT_RUN_RES_ID \
--api-version 2019-12-01-preview

ACR 传输故障排除

查看 ACR 传输故障排除以获取故障排除指南。

后续步骤

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

通过

使用 ARM 模板进行 ACR 传输

满足先决条件

请考虑使用 Az CLI 扩展

使用资源管理器创建 ExportPipeline

导出选项

创建资源

选项 1：创建资源并启用系统分配的标识

选项 2：创建资源并提供用户分配的标识

使用资源管理器创建 ImportPipeline

导入选项

创建资源

选项 1：创建资源并启用系统分配的标识

选项 2：创建资源并提供用户分配的标识

使用资源管理器创建用于导出的 PipelineRun

传输 blob（可选）

触发 ImportPipeline 资源

使用资源管理器创建用于导入的 PipelineRun（可选）

重新部署 PipelineRun 资源

删除管道资源

ACR 传输故障排除

后续步骤

其他资源