无法将映像从Azure 容器注册表拉取到 Azure Web 应用

2024-08-22

本文提供有关将映像从 Azure 容器注册表拉取到 Azure Web 应用时可能遇到的最常见错误的指南。

症状和初始故障排除

建议通过检查容器注册表运行状况来启动故障排除。

若要检查容器注册表运行状况，请运行以下命令：

az acr check-health --name <myregistry> --ignore-errors --yes

如果检测到问题，则结果包括错误代码和说明。有关这些错误和可能的解决方案的详细信息，请参阅运行状况检查错误参考。

注意

如果收到 Helm 相关或与公证相关的错误，则这并不意味着容器注册表或 AKS 不起作用或出现问题。它只是指示未安装 Helm 或 Notary 等问题，或者 Azure CLI 与当前安装的 Helm 或 Notary 版本不兼容。

接下来，确定对故障排除至关重要的拉取相关错误消息：

登录到 Azure 门户。
在 Web 应用中，选择 “部署中心>日志”。选择提交以查看日志详细信息。还可以通过在“监视”部分中查看日志流来实时查看映像拉取过程的日志。

以下部分可帮助你排查 Web 应用日志中显示的最常见错误。

错误 1：未授权

Head \" https://<acr-name>.azurecr.io/v2/<repository>/manifests/<tag>\": unauthorized

基于用户的管理员身份验证的解决方案

“未经授权的”错误可能是由不正确的管理员凭据引起的。这包括在 Web 应用环境变量中配置的登录服务器、用户名或密码。

若要解决该问题，请执行以下步骤：

在Azure 门户中，导航到注册表容器。在 “设置” 部分中，选择“ 访问密钥”。检查登录服务器、用户名和密码的管理员用户凭据设置。
导航到 Web 应用。在 “设置” 部分中，选择“ 环境变量”。
确保为容器注册表（登录服务器、用户名、密码）配置的三个变量与注册表容器中的管理员用户凭据设置匹配。

基于托管标识的身份验证的解决方案

使用 Azure Web 应用的基于托管标识的身份验证时， Microsoft.ContainerRegistry/registries/pull/read 必须将权限分配给托管标识才能执行拉取操作。

包含权限的 Microsoft.ContainerRegistry/registries/pull/read Azure 内置角色如下：

AcrPull
AcrPush
ReaderContributor
所有者

有关详细信息，请参阅 Azure 容器注册表角色和权限。

从容器注册表启动拉取操作时，AcrPull 角色会自动分配给 Azure Web 应用托管标识。无需手动添加权限。但是，必须确保角色分配创建不受 Azure 策略（例如 Azure 策略）阻止。此外，请验证角色分配是否已删除。

错误 2：找不到标记<>标记的清单

DockerApiException : Docker API responded with status code=NotFound, response={"message":"manifest for <acr-name>.azurecr.io/<repository>:<tag> not found: manifest unknown: manifest tagged by \"<tag>\" is not found"}

解决方案：确保标记存在

错误消息指示找不到与要拉取的图像关联的标记。请确保标记存在于关联的存储库和注册表中。

若要使用 Azure CLI 查找关联的存储库和注册表中的标记，请运行以下命令：

az acr repository show-tags -n <ContainerRegistryName> --repository <RepositoryName>

若要使用Azure 门户查找关联存储库和注册表中的标记，请执行以下步骤：

导航到注册表容器。在“服务”下，选择“存储库”，打开关联的存储库，然后检查标记列表。

注意

az acr repository show-tags 命令，或检查Azure 门户中的存储库仅在容器注册表网络规则允许时有效。

错误 3：不允许使用 IP 的客户端访问

DockerApiException: Docker API responded with status code=InternalServerError, response={"message":"Head \"https:// <acr-name>.azurecr.io/v2/<repository>/manifests/<tag>\": denied: client with IP '<web-app-outbound-ip>' is not allowed access. Refer https://aka.ms/acr/firewall to grant access."}

解决方案 1：确保容器注册表内置防火墙允许设备的 IP 地址

默认情况下，容器注册表接受来自所有网络的 Internet 连接。容器注册表具有内置防火墙，可以限制对特定 IP 地址或CIDR 的访问，或者完全禁用公用网络访问。

如果容器注册表的内置防火墙阻止了 Web 应用的 IP 地址，则可能会出现此问题。

若要解决此问题，请确保内置防火墙允许必须拉取映像的 Web 应用的出站 IP 地址。

若要查找 Web 应用的出站 IP 地址，请执行以下步骤：

在Azure 门户中，导航到 Web 应用。
在 “概述 ”页上，找到 出站 IP 地址，然后选择“ 显示更多 ”以获取出站 IP 地址的完整列表

若要使用 Azure CLI 查找 Web 应用的出站 IP 地址，请参阅Azure App 服务中查找出站 IP 地址。

解决方案 2：为 Web 应用配置虚拟网络集成

如果必须完全禁用公用网络访问，或者只允许容器注册表中的所选网络，而无需手动添加 Web 应用的 IP 地址，另一个选项是私下拉取映像。若要以私密方式拉取映像，必须使用专用终结点配置容器注册表，并为 Web 应用启用虚拟网络集成。

可以按照以下步骤在 Web 应用中配置虚拟网络集成：

在Azure 门户中，导航到 Web 应用，然后选择“网络”。
在“出站流量配置”下，配置虚拟网络集成，选择“添加虚拟网络集成”，然后指定订阅、虚拟网络和子网。
在 “虚拟网络配置 ”页上，确保 已选择“容器映像拉取 ”选项。

若要通过虚拟网络拉取映像，必须在 Web 应用的部署中心启用 VNet 上的拉取映像。此外，如果容器注册表已禁用公共访问或设置为特定网络，则可能会收到“无法加载 ACR 标记 - 失败”消息，如以下示例所示。在这种情况下，预期会出现此错误。如果发生这种情况，则图像和标记的下拉选项将不可用。必须手动输入映像和标记。

后续步骤

如果此故障排除指南无法解决问题，请考虑以下事项：

检查与子网关联的网络安全组和路由表。如果虚拟设备（如防火墙）控制子网之间的流量，请查看防火墙及其访问规则。

使用 Kudu 服务进行其他故障排除。可以连接到 Kudu 服务。例如，使用 Bash 通过运行 nslookup <acr-name>.azurecr.io或通过使用 tcpping <acr-name>.azurecr.io检查连接来测试 DNS 解析。

联系我们寻求帮助

如果你有任何疑问或需要帮助，请创建支持请求或联系 Azure 社区支持。你还可以将产品反馈提交到 Azure 反馈社区。

通过