排查与注册表相关的网络问题Troubleshoot network issues with registry

本文将帮助你排查在访问位于虚拟网络中或防火墙或代理服务器后面的 Azure 容器注册表时可能遇到的问题。This article helps you troubleshoot problems you might encounter when accessing an Azure container registry in a virtual network or behind a firewall or proxy server.

症状Symptoms

可能包括以下一项或多项:May include one or more of the following:

  • 无法推送或拉取映像,出现错误 dial tcp: lookup myregistry.azurecr.cnUnable to push or pull images and you receive error dial tcp: lookup myregistry.azurecr.cn
  • 无法推送或拉取映像,出现错误 Client.Timeout exceeded while awaiting headersUnable to push or pull images and you receive error Client.Timeout exceeded while awaiting headers
  • 无法推送或拉取映像,出现 Azure CLI 错误 Could not connect to the registry login serverUnable to push or pull images and you receive Azure CLI error Could not connect to the registry login server
  • 无法将映像从注册表拉取到 Azure Kubernetes 服务或其他 Azure 服务Unable to pull images from registry to Azure Kubernetes Service or another Azure service
  • 无法访问 HTTPS 代理后面的注册表,出现错误 Error response from daemon: login attempt failed with status: 403 ForbiddenError response from daemon: Get <registry>: proxyconnect tcp: EOF Login failedUnable to access a registry behind an HTTPS proxy and you receive error Error response from daemon: login attempt failed with status: 403 Forbidden or Error response from daemon: Get <registry>: proxyconnect tcp: EOF Login failed
  • 无法配置虚拟网络设置,出现错误“Failed to save firewall and virtual network settings for container registryUnable to configure virtual network settings and you receive error Failed to save firewall and virtual network settings for container registry
  • 无法在 Azure 门户中访问或查看注册表设置,或者无法使用 Azure CLI 管理注册表Unable to access or view registry settings in Azure portal or manage registry using the Azure CLI
  • 无法添加或修改虚拟网络设置或公共访问规则Unable to add or modify virtual network settings or public access rules
  • Azure 容器注册表任务无法推送或拉取映像ACR Tasks is unable to push or pull images
  • Azure 安全中心无法扫描注册表中的映像,或者扫描结果未显示在 Azure 安全中心内Azure Security Center can't scan images in registry, or scan results don't appear in Azure Security Center
  • 在尝试访问使用专用终结点配置的注册表时,你收到错误 host is not reachableYou receive error host is not reachable when attempting to access a registry configured with a private endpoint.

原因Causes

  • 客户端防火墙或代理阻止访问 - 解决方案A client firewall or proxy prevents access - solution
  • 注册表上的公用网络访问规则阻止访问 - 解决方案Public network access rules on the registry prevent access - solution
  • 虚拟网络配置阻止访问 - 解决方案Virtual network configuration prevents access - solution
  • 你尝试将 Azure 安全中心或某些其他的 Azure 服务与具有专用终结点、服务终结点或公共 IP 访问规则的注册表集成 - 解决方案You attempt to integrate Azure Security Center or certain other Azure services with a registry that has a private endpoint, service endpoint, or public IP access rules - solution

进一步诊断Further diagnosis

运行 az acr check-health 命令可详细了解注册表环境的运行状况,以及对目标注册表的访问(可选)。Run the az acr check-health command to get more information about the health of the registry environment and optionally access to a target registry. 例如,诊断某些网络连接或配置问题。For example, diagnose certain network connectivity or configuration problems.

参阅检查 Azure 容器注册表的运行状况以查看命令示例。See Check the health of an Azure container registry for command examples. 如果报告了错误,请查看错误参考和以下部分,以了解建议的解决方案。If errors are reported, review the error reference and the following sections for recommended solutions.

如果在将 Azure Kubernetes 服务与集成注册表配合使用时遇到问题,请运行 az aks check-acr 命令,以验证 AKS 群集是否可以访问该注册表。If you're experiencing problems using an Azure Kubernetes Service with an integrated registry, run the az aks check-acr command to validate that the AKS cluster can reach the registry.

备注

当注册表身份验证或授权存在问题时,也可能出现一些网络连接症状。Some network connectivity symptoms can also occur when there are issues with registry authentication or authorization. 请参阅注册表登录故障排除See Troubleshoot registry login.

可能的解决方案Potential solutions

配置客户端防火墙访问权限Configure client firewall access

若要从客户端防火墙或代理服务器后面访问注册表,请将防火墙规则配置为可访问注册表的公共 REST 和数据终结点。To access a registry from behind a client firewall or proxy server, configure firewall rules to access the registry's public REST and data endpoints. 如果启用了专用数据终结点,则需要用于访问以下终结点的规则:If dedicated data endpoints are enabled, you need rules to access:

  • REST 终结点:<registryname>.azurecr.cnREST endpoint: <registryname>.azurecr.cn
  • 数据终结点:<registry-name>.<region>.data.azurecr.cnData endpoint(s): <registry-name>.<region>.data.azurecr.cn

对于异地复制的注册表,请为每个区域副本配置对数据终结点的访问权限。For a geo-replicated registry, configure access to the data endpoint for each regional replica.

在 HTTPS 代理后面,确保 Docker 客户端和 Docker 守护程序均已针对代理行为进行了配置。Behind an HTTPS proxy, ensure that both your Docker client and Docker daemon are configured for proxy behavior. 如果更改了 Docker 守护程序的代理设置,必需重启该守护程序。If you change your proxy settings for the Docker daemon, be sure to restart the daemon.

ContainerRegistryLoginEvents 表中的注册表资源日志可能有助于诊断尝试的连接被阻止的问题。Registry resource logs in the ContainerRegistryLoginEvents table may help diagnose an attempted connection that is blocked.

相关链接:Related links:

配置对注册表的公共访问权限Configure public access to registry

如果通过 Internet 访问注册表,请确认注册表允许从客户端通过公用网络进行的访问。If accessing a registry over the internet, confirm the registry allows public network access from your client. 默认情况下,Azure 容器注册表允许从所有网络访问公共注册表终结点。By default, an Azure container registry allows access to the public registry endpoints from all networks. 注册表可以将访问限制为来自所选网络或所选 IP 地址。A registry can limit access to selected networks, or selected IP addresses.

如果为具有服务终结点的虚拟网络配置了注册表,禁用公用网络访问还会禁止通过服务终结点进行访问。If the registry is configured for a virtual network with a service endpoint, disabling public network access also disables access over the service endpoint. 如果为具有专用链接的虚拟网络配置了注册表,则 IP 网络规则不适用于注册表的专用终结点。If your registry is configured for a virtual network with Private Link, IP network rules don't apply to the registry's private endpoints.

相关链接:Related links:

配置 VNet 访问权限Configure VNet access

确认虚拟网络为专用链接配置了专用终结点,或者配置了服务终结点(预览版)。Confirm that the virtual network is configured with either a private endpoint for Private Link or a service endpoint (preview). 当前不支持 Azure Bastion 终结点。Currently an Azure Bastion endpoint isn't supported.

如果配置了专用终结点,请确认 DNS 已将注册表的公共 FQDN(例如,myregistry.azurecr.cn)解析为注册表的专用 IP 地址。If a private endpoint is configured, confirm that DNS resolves the registry's public FQDN such as myregistry.azurecr.cn to the registry's private IP address. 使用网络实用工具(如 dignslookup)进行 DNS 查找。Use a network utility such as dig or nslookup for DNS lookup. 确保为注册表 FQDN 和每个数据终结点 FQDN 配置 DNS 记录Ensure that DNS records are configured for the registry FQDN and for each of the data endpoint FQDNs.

查看用于限制从网络中的其他资源发往注册表的流量的 NSG 规则和服务标记。Review NSG rules and service tags used to limit traffic from other resources in the network to the registry.

如果配置了注册表的服务终结点,请确认用于允许从该网络子网进行访问的网络规则已添加到注册表。If a service endpoint to the registry is configured, confirm that a network rule is added to the registry that allows access from that network subnet. 服务终结点仅支持从网络中的虚拟机和 AKS 群集进行访问。The service endpoint only supports access from virtual machines and AKS clusters in the network.

若要使用其他 Azure 订阅中的虚拟网络限制注册表访问,请确保在该订阅中注册 Microsoft.ContainerRegistry 资源提供程序。If you want to restrict registry access using a virtual network in a different Azure subscription, ensure that you register the Microsoft.ContainerRegistry resource provider in that subscription. 使用 Azure 门户、Azure CLI 或其他 Azure 工具为 Azure 容器注册表注册资源提供程序Register the resource provider for Azure Container Registry using the Azure portal, Azure CLI, or other Azure tools.

如果在网络中配置了 Azure 防火墙或类似的解决方案,请检查是否已允许来自其他资源(如 AKS 群集)的出口流量到达注册表终结点。If Azure Firewall or a similar solution is configured in the network, check that egress traffic from other resources such as an AKS cluster is enabled to reach the registry endpoints.

相关链接:Related links:

配置服务访问Configure service access

目前,多个 Azure 服务不允许访问具有网络限制的容器注册表:Currently, access to a container registry with network restrictions isn't allowed from several Azure services:

  • Azure 安全中心无法在限制对专用终结点、所选子网或 IP 地址进行访问的注册表中执行映像漏洞扫描Azure Security Center can't perform image vulnerability scanning in a registry that restricts access to private endpoints, selected subnets, or IP addresses.
  • 某些 Azure 服务(包括 Azure 应用服务和 Azure 容器实例)的资源无法访问具有网络限制的容器注册表。Resources of certain Azure services are unable to access a container registry with network restrictions, including Azure App Service and Azure Container Instances.

如果需要使用容器注册表访问或集成这些 Azure 服务,请去除网络限制。If access or integration of these Azure services with your container registry is required, remove the network restriction. 例如,删除注册表的专用终结点,或者删除或修改注册表的公共访问规则。For example, remove the registry's private endpoints, or remove or modify the registry's public access rules.

从 2021 年 1 月开始,可以将受网络限制的注册表配置为允许从所选的受信任服务访问Starting January 2021, you can configure a network-restricted registry to allow access from select trusted services.

相关链接:Related links:

高级故障排除Advanced troubleshooting

如果在注册表中启用了收集资源日志,请查看 ContainterRegistryLoginEvents 日志。If collection of resource logs is enabled in the registry, review the ContainterRegistryLoginEvents log. 此日志存储身份验证事件和状态,包括传入标识和 IP 地址。This log stores authentication events and status, including the incoming identity and IP address. 查询此日志可获得有关注册表身份验证失败的信息。Query the log for registry authentication failures.

相关链接:Related links:

后续步骤Next steps

如果此处无法解决你的问题,请参阅以下选项。If you don't resolve your problem here, see the following options.