排查Azure 容器注册表中的推送错误

2024-11-19

本文可帮助你排查将映像或项目推送到 Azure 容器注册表时可能会遇到的问题。

症状和初始故障排除

建议通过检查容器注册表运行状况开始进行故障排除。

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

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

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

注意

如果收到 Helm 相关或与公证相关的错误，这不一定意味着容器注册表或Microsoft Azure Kubernetes 服务（AKS）不起作用或出现问题。它仅指示未安装 Helm 或 Notary 之类的问题，或者 Azure CLI 与当前安装的 Helm 或 Notary 版本不兼容。

在推送到Azure 容器注册表之前验证身份验证。身份验证是授予推送操作所需的权限所必需的。如果在尝试通过 Azure 容器注册表进行身份验证时遇到问题，请参阅使用 Azure 容器注册表进行身份验证并排查Azure 容器注册表身份验证错误。

以下部分可帮助你排查推送操作期间出现的最常见错误。

错误 1：此注册表上不允许此操作

The operation is disallowed on this registry, repository or image. View troubleshooting steps at https://aka.ms/acr/faq/#why-does-my-pull-or-push-request-fail-with-disallowed-operation

解决方案 1：确保存储库或映像未锁定

此问题可能是由于为存储库或映像禁用了写入操作引起的。此状态拒绝删除和推送操作。 Azure 容器注册表允许设置changeableAttributes属性以避免意外删除，或者通过存储库或容器映像执行写入或读取操作。

可以使用以下命令之一检查当前存储库属性：

# Check the repository attributes.
az acr repository show --name myregistry --repository myrepo --output jsonc

# Check the image attributes.
az acr repository show --name myregistry --image myrepo:tag --output jsonc

# Check the image attributes by manifest digest 
az acr repository show --name myregistry --image myrepo@sha256:123456abcdefg --output jsonc

输出示例 az acr repository show ：

{
  "changeableAttributes": {
    "deleteEnabled": false,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": false
  },
  "createdTime": "2024-08-20T15:22:51.0355721Z",
  "imageName": "myImage_0a1c809cc2eb596028fcf7a68e498e09",
  "lastUpdateTime": "2024-08-20T15:23:01.2739647Z",
  "manifestCount": 1,
  "registry": "myACR.azurecr.io",
  "tagCount": 2
}

如果设置为 writeEnabled false，则表示存储库或映像已锁定在推送操作中。可以使用以下命令之一解锁存储库：

#unlock the repository
az acr repository update --name myregistry --repository myrepo --write-enabled true 

#unlock the image by tag
az acr repository update --name myregistry --image myrepo:tag --write-enabled true 

#unlock the image by manifest digest
az acr repository update --name myregistry --image myrepo@sha256:123456abcdefg --write-enabled true

解决方案 2：验证容器注册表是否达到存储限制

另一个潜在问题是容器注册表可能已达到其存储限制。容器注册表的最大存储容量为 40 TiB。有关详细信息，请参阅服务层级功能和限制。

如果需要超出此限制的存储，请联系 Azure 支持部门。

错误 2：请求在等待连接时已取消（等待标头时超出 Client.Timeout）

Get "https://yourARC.azurecr.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

提示

容器注册表登录服务器也称为注册表 REST API 终结点。登录服务器名称的格式 <registry-name>.azurecr.io 为（必须全部小写）。

身份验证和注册表管理操作通过注册表的公共登录服务器进行处理。

如果设备是受限网络环境的一部分，请检查是否有防火墙、代理服务器、访问控制列表或 ISP 限制可能会阻止连接。

若要在端口 443 上手动测试设备与容器注册表登录服务器之间的连接，可以使用以下网络工具telnet：nc

telnet <acr-name>.azurecr.io 443

nc -vz <acr-name>.azurecr.io 443 -w 10

示例输出：

nc: connect to <acr-name>.azurecr.io 443 port (TCP) failed: Connection timeout

如果从 Azure 资源推送到容器注册表，请执行以下步骤来排查该问题。

步骤 1：检查与 Azure 资源关联的 NSG

检查前面提到的或telnet命令的nc输出。如果显示超时错误，请检查网络安全组（NSG），并确保不会阻止容器注册表登录服务器的 IP 地址。

若要检查 NSG 是否阻止容器注册表登录服务器的 IP 地址，请执行以下步骤：

找到容器注册表登录服务器的 IP 地址。
1. 在Azure 门户中，打开容器注册表。
2. 选择“概述”，并检查登录服务器的完全限定域名（FQDN）。
3. 使用工具 nslookup 查找 FQDN 的 IP 地址： nslookup <acr-name>.azurecr.io。
在Azure 门户中，转到网络观察程序并选择 NSG 诊断。
在窗体字段中，指定以下值：
- 协议：TCP
- 方向：出站
- 源类型：IPv4 地址/CIDR
- IPv4 地址/CIDR：Azure 资源的 IP 地址
- 目标 IP 地址：容器注册表登录服务器的 IP 地址
- 目标端口：443
选择“运行 NSG 诊断”按钮，并检查“流量”状态。流量状态可以是 “允许 ”或 “拒绝”。 “拒绝”表示 NSG 正在阻止 Azure 资源与登录服务器之间的流量。如果状态为“拒绝”，将显示 NSG 名称。

若要解决此问题，请在 NSG 级别进行杂项更改，以允许 Azure 设备和端口 443 上的容器注册表登录服务器之间的连接。

步骤 2：检查与 Azure 资源的子网关联的路由表或防火墙

查看 nc 或 telnet 命令的输出。如果显示超时：

确保路由表不会将流量丢弃到容器注册表登录服务器。如果与容器注册表登录服务器关联的路由的下一跃点设置为 “无”，则会丢弃流量。有关详细信息，请参阅 “下一跃点类型：无”。
如果路由表向虚拟设备（如防火墙）发送流量，请确保防火墙不会阻止端口 443 上的容器注册表登录服务器的流量。有关详细信息，请参阅配置规则以访问防火墙后的 Azure 容器注册表。

错误 3：被拒绝，不允许访问客户端

denied: {"errors":[{"code":"DENIED","message":"client with IP \u0027<your-device-IP>\u0027 is not allowed access. Refer https://aka.ms/acr/firewall to grant access."}]}

解决方案：确保内置防火墙允许设备的 IP 地址

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

如果内置防火墙不允许设备 IP 地址，则禁用或限制对特定 IP 地址或CIDR 的访问可能会生成 DENIED 错误。

若要解决此问题，请确保容器注册表的内置防火墙允许用于执行推送操作的设备 IP 地址。有关详细信息，请参阅为 Azure 容器注册表配置公共 IP 网络规则。或者，如果禁用了公共网络访问，则可以使用专用终结点配置连接。

联系我们寻求帮助

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

通过