向容器注册表导入容器映像

2025-05-06

可以轻松将容器映像导入（复制）到 Azure 容器注册表中，无需使用 Docker 命令。例如，将映像从开发注册表导入到生产注册表，或者从公共注册表复制基础映像。

Azure 容器注册表可灵活应对许多常见方案，以便从现有注册表复制映像和其他工件：

从公共注册表导入映像
从其他 Azure 容器映像（在同一个或不同的 Azure 订阅或租户中）导入映像或 OCI 工件（包括 Helm 3 图表）
从非 Azure 专用容器注册表导入

与使用 Docker CLI 命令相比，将映像导入到 Azure 容器注册表具有以下优点：

如果你的客户端环境不需要本地 Docker 安装，则可导入任何容器映像，无需考虑受支持的 OS 类型。
如果导入多体系结构映像（例如正式的 Docker 映像），则会复制清单列表中指定的所有体系结构和平台的映像。
如果有权访问目标注册表，则不需要注册表的公共终结点。

重要

导入映像要求外部注册表支持 RFC 7233。建议使用支持 RFC 7233 范围的注册表，同时将 az acr import 命令与注册表 URI 配合使用以避免失败。

限制

对于导入的映像，清单的最大数目为 50。

Azure CLI
Azure PowerShell

若要导入容器映像，本文要求在 Azure Cloud Shell 中或本地（建议使用 2.0.55 或更高版本）运行 Azure CLI。运行 az --version 即可查找版本。如果需要进行安装或升级，请参阅安装 Azure CLI。

注意

如果需要在多个 Azure 区域中分布相同的容器映像，则 Azure 容器注册表还支持异地复制。通过对注册表（需要高级服务层）进行异地复制，可以使用单个注册表的相同映像和标记名称为多个区域提供服务。

重要

自 2021 年 1 月起，已引入对两个 Azure 容器注册表的映像导入的更改：

如果要向/从网络受限的 Azure 容器注册表导入内容，需要受限的注册表允许受信任的服务进行访问，以绕过该网络。默认情况下，此设置处于启用状态，允许导入。如果刚创建的具有专用终结点或注册表防火墙规则的注册表中未启用该设置，导入将失败。
在用作导入源或目标的现有网络受限 Azure 容器注册表中，可以选择且建议选择启用此网络安全功能。

如果还没有 Azure 容器注册表，请创建注册表。有关步骤，请参阅快速入门：使用 Azure CLI 创建专用容器注册表。

若要将图片导入 Azure 容器注册表，您的身份必须具有在目标注册表（Container Registry Data Importer and Data Reader 角色）中触发导入的权限。请参阅 Azure 容器注册表 Entra 权限和角色概述。

从公共注册表导入

重要

要从公共注册表向网络受限的 Azure 容器注册表导入内容，需要受限注册表才能允许受信任的服务进行访问，从而绕过网络。默认情况下，此设置处于启用状态，即允许导入。如果刚创建的具有专用终结点或注册表防火墙规则的注册表中未启用该设置，导入将失败。

从 Docker 中心导入

Azure CLI
Azure PowerShell

例如，使用 az acr import 命令将多体系结构 hello-world:latest 映像从 Docker 中心导入到名为 myregistry 的注册表。由于 hello-world 是来自 Docker 中心的官方映像，因此该映像位于默认的 library 存储库中。 --source 映像参数的值中包含存储库名称和（可选）标记。（可以选择性根据映像的清单摘要而不是标签来标识映像，这确保映像为特定版本。）

az acr import \
  --name myregistry \
  --source docker.io/library/hello-world:latest \
  --image hello-world:latest

可运行 az acr manifest list-metadata 命令来验证是否有多个清单与此映像关联：

az acr manifest list-metadata \
  --name hello-world \
  --registry myregistry

若要按摘要方式导入项目，而不添加标记，请执行以下操作：

az acr import \
   --name myregistry \
   --source docker.io/library/hello-world@sha256:abc123 \
   --repository hello-world

如果有 Docker Hub 帐户，则建议从 Docker Hub 导入映像时使用凭据。将 Docker Hub 用户名和密码，或者个人访问令牌作为参数传递到 az acr import。以下示例使用 Docker Hub 凭据从 Docker Hub 中的 tensorflow 存储库导入公共映像：

az acr import \
  --name myregistry \
  --source docker.io/tensorflow/tensorflow:latest-gpu \
  --image tensorflow:latest-gpu
  --username <Docker Hub user name>
  --password <Docker Hub token>

例如，使用 Import-AzContainerRegistryImage 命令将多体系结构 hello-world:latest 映像从 Docker Hub 导入到名为“myregistry”的注册表。由于 hello-world 是来自 Docker 中心的官方映像，因此该映像位于默认的 library 存储库中。在 -SourceImage 参数的值中，包含存储库名称，以及标记（可选）。（可以选择性根据映像的清单摘要而不是标签来标识映像，这确保映像为特定版本。）

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri docker.io -SourceImage library/hello-world:latest

可以通过运行 Get-AzContainerRegistryManifest cmdlet 来验证是否多个清单与此映像关联：

Get-AzContainerRegistryManifest -RepositoryName library/hello-world -RegistryName myregistry

如果有 Docker Hub 帐户，则建议从 Docker Hub 导入映像时使用凭据。将 Docker Hub 用户名和密码，或者个人访问令牌作为参数传递到 Import-AzContainerRegistryImage。以下示例使用 Docker Hub 凭据从 Docker Hub 中的 tensorflow 存储库导入公共映像：

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri docker.io -SourceImage tensorflow/tensorflow:latest-gpu -Username <Docker Hub user name> -Password <Docker Hub token>

从 Microsoft 容器注册表导入

例如，从 Microsoft Container Registry 中的 ltsc2019 存储库导入 windows Windows Server Core 映像。

Azure CLI
Azure PowerShell

az acr import \
--name myregistry \
--source mcr.microsoft.com/windows/servercore:ltsc2019 \
--image servercore:ltsc2019

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri mcr.microsoft.com -SourceImage windows/servercore:ltsc2019

从同一 AD 租户中的 Azure 容器注册表导入

可以使用集成的 Microsoft Entra 权限从同一 AD 租户中的 Azure 容器注册表导入映像。

你的标识必须具有查看和拉取源注册表中的映像、标签以及 OCI 引用来源的权限。
- 对于已启用 ABAC 的源注册表，必须在源注册表中同时具有 Container Registry Repository Reader 角色和 Container Registry Repository Catalog Lister 角色。
- 对于非 ABAC 源注册表，必须在源注册表上具有 AcrPull 角色。
你的标识还必须具有读取映像和触发目标注册表导入的权限（Container Registry Data Importer and Data Reader 角色）。
注册表可以位于同一 Active Directory 租户的同一或不同 Azure 订阅中。
已禁用对源注册表的公共访问。如果禁用了公共访问，请通过资源 ID 而不是注册表登录服务器名称指定源注册表。
具有专用终结点的源注册表和/或目标注册表或者注册表防火墙规则必须确保受限注册表允许受信任的服务访问网络。

从同一订阅的注册表中导入

例如，在同一 Azure 订阅中，将 aci-helloworld:latest 映像从源注册表 mysourceregistry 导入到 myregistry。

Azure CLI
Azure PowerShell

az acr import \
  --name myregistry \
  --source mysourceregistry.azurecr.io/aci-helloworld:latest \
  --image aci-helloworld:latest

以下示例将 aci-helloworld:latest 映像从源注册表 mysourceregistry 导入到 myregistry 中，在该源注册表中禁止访问注册表的公共终结点。使用 --registry 参数提供源注册表的资源 ID。注意，--source 参数只指定源存储库和标记，而不指定注册表登录服务器名称。

az acr import \
  --name myregistry \
  --source aci-helloworld:latest \
  --image aci-helloworld:latest \
  --registry /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry

下面的示例通过清单摘要（SHA-256 哈希代码，表示为 sha256:...）而非标记导入映像：

az acr import \
  --name myregistry \
  --source mysourceregistry.azurecr.io/aci-helloworld@sha256:123456abcdefg

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri mysourceregistry.azurecr.io -SourceImage aci-helloworld:latest

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryResourceId '/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry' -SourceImage aci-helloworld:latest

下面的示例通过清单摘要（SHA-256 哈希代码，表示为 sha256:...）而非标记导入映像：

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri mysourceregistry.azurecr.io -SourceImage aci-helloworld@sha256:123456abcdefg

从不同订阅的注册表导入

注意

要将映像从一个注册表导入另一个注册表，源注册表和目标注册表必须确保两个区域都在订阅的资源提供程序下注册了 Azure 容器注册表 (ACR)。

Azure CLI
Azure PowerShell

在下面的示例中，mysourceregistry 与 myregistry 处于同一 Active Directory 租户的不同订阅中。使用 --registry 参数提供源注册表的资源 ID。注意，--source 参数只指定源存储库和标记，而不指定注册表登录服务器名称。

az acr import \
  --name myregistry \
  --source aci-helloworld:latest \
  --image aci-hello-world:latest \
  --registry /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryResourceId '/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry' -SourceImage aci-helloworld:latest

使用服务主体凭据从注册表导入

若要从无法使用集成的 Active Directory 权限访问的注册表中导入，可以将服务主体凭据（如果可用）用于源注册表。提供对源注册表具有正确角色分配访问权限的 Microsoft Entra 服务主体的 appID 和密码。

对于 Microsoft Entra 服务主体，请确保已应用 Container Registry Repository Reader（适用于已启用 ABAC 的注册表）或 AcrPull（适用于非 ABAC 注册表）。

服务主体适用于需将映像导入到注册表的生成系统和其他无人参与系统。

Azure CLI
Azure PowerShell

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.io/sourcerrepo:tag \
  --image targetimage:tag \
  --username <SP_App_ID> \
  --password <SP_Passwd>

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri sourceregistry.azurecr.io -SourceImage sourcerrepo:tag -Username <SP_App_ID> -Password <SP_Passwd>

从不同 AD 租户中的 Azure 容器注册表导入

若要从不同 Microsoft Entra 租户中的 Azure 容器注册表导入，请通过登录服务器名称指定源注册表，并提供支持对注册表进行拉取访问的凭据。

不支持通过公共访问禁用的注册表进行跨租户导入。

使用用户名和密码进行跨租户导入

例如，使用非 Microsoft Entra 存储库范围内的令牌和密码，或者使用向源注册表正确分配角色的 Microsoft Entra 服务主体的 appID 和密码。

对于 Microsoft Entra 服务主体，请确保在源注册表上，Container Registry Repository Reader 已分配到（对于已启用 ABAC 的注册表），或者 AcrPull 已分配到（对于非 ABAC 注册表）。

Azure CLI
Azure PowerShell

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.io/sourcerrepo:tag \
  --image targetimage:tag \
  --username <SP_App_ID> \
  --password <SP_Passwd>

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri sourceregistry.azurecr.io -SourceImage sourcerrepo:tag -Username <SP_App_ID> -Password <SP_Passwd>

使用访问令牌进行跨租户导入

不支持通过公共访问禁用的注册表进行跨租户导入。

若要使用源租户中具有注册表权限的标识访问源注册表，可以获取访问令牌：

Azure CLI
Azure PowerShell

# Login to Azure CLI with the identity, for example a user-assigned managed identity
az login --identity --username <identity_ID>

# Get access token returned by `az account get-access-token`
az account get-access-token

在目标租户中，将访问令牌作为密码传递给 az acr import 命令。源注册表指定登录服务器名称。请注意，此命令中不需要用户名：

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.io/sourcerrepo:tag \
  --image targetimage:tag \
  --password <access-token>

# Login to Azure PowerShell with the identity, for example a user-assigned managed identity
Connect-AzAccount -Identity -AccountId <identity_ID>

# Get access token returned by `Get-AzAccessToken`
Get-AzAccessToken

在目标租户中，将访问令牌作为密码传递到 Import-AzContainerRegistryImage cmdlet。源注册表指定登录服务器名称。请注意，此命令中不需要用户名：

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri sourceregistry.azurecr.io -SourceImage sourcerrepo:tag -Password <access-token>

从非 Azure 专用容器注册表导入

通过指定启用了对注册表进行拉取访问的凭据，从非 Azure 专用注册表导入映像。例如，从专用 Docker 注册表拉取映像：

Azure CLI
Azure PowerShell

az acr import \
  --name myregistry \
  --source docker.io/sourcerepo/sourceimage:tag \
  --image sourceimage:tag \
  --username <username> \
  --password <password>

Import-AzContainerRegistryImage -RegistryName myregistry -ResourceGroupName myResourceGroup -SourceRegistryUri docker.io/sourcerepo -SourceImage sourcerrepo:tag -Username <username> -Password <password>

注意

如果要从具有 IP 规则的非 Azure 专用注册表导入，请执行以下步骤。

排查导入容器映像问题

症状和原因

The remote server may not be RFC 7233 compliant
- distribution-spec 允许使用范围标头形式 Range: bytes=<start>-<end>。但是，远程服务器可能不符合 RFC 7233 要求。
Unexpected response status code
- 执行范围查询时，请从源存储库获取意外响应状态代码。
Unexpected length of body in response
- 接收到的内容长度与预期大小不匹配。预期大小由 blob 大小和范围标头决定。

后续步骤

在本文中，你了解了如何从公共注册表或其他专用注册表将容器映像导入 Azure 容器注册表。

Azure CLI
Azure PowerShell

关于其他映像导入选项，请参阅 az acr import 命令参考。

映像导入可帮助你将内容移动到其他 Azure 区域、订阅或 Microsoft Entra 租户中的容器注册表。有关详细信息，请参阅手动将容器注册表移到另一区域。
从网络受限的容器注册表禁用工件导出。

通过