排查映像拉取问题

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本页面可帮助您解决 Google Kubernetes Engine (GKE) 中的映像拉取流程问题。如果您使用的是映像流式传输，请改为参阅排查映像流式传输问题，获取相关建议。本页重点介绍标准映像拉取。

本页面适用于希望确保其应用成功部署的应用开发者，以及希望了解映像拉取失败根本原因并验证平台配置的平台管理员和运维人员。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE Enterprise 用户角色和任务。

映像拉取流程是 Kubernetes（因此也是 GKE）从注册表中检索容器映像的方式。当图片拉取失败时，您可能会注意到应用运行缓慢，或者应用完全无法运行。

如需确定应用无法运行是否是由映像拉取导致的，本页面可帮助您查找并了解相关错误消息，从而诊断映像拉取失败问题。然后，您将学习解决以下导致图片拉取失败的常见原因：

• 身份验证设置：您的集群缺少访问容器映像注册表的必要权限。
• 网络连接：由于 DNS 问题、防火墙规则或使用网络隔离的集群无法访问互联网，您的集群无法连接到注册表。
• 注册表中未找到映像：指定的映像名称或标记不正确、映像已被删除或注册表不可用。
• 性能限制：图片大小过大、磁盘 I/O 缓慢或网络拥塞都可能会导致拉取速度缓慢或超时。
• 映像架构不兼容：映像的构建目标是与您的 GKE 节点池不同的 CPU 架构。
• 架构版本不兼容：您可能将 containerd 2.0 或更高版本与 v1 Docker 架构搭配使用，而我们不支持这种组合。

如果您已看到特定事件消息，请在此页面中搜索该消息，然后按照列出的问题排查步骤操作。如果您还没有看到消息，请按顺序完成以下部分。如果问题仍然存在，请与 Cloud Customer Care 团队联系。

了解映像拉取

在开始问题排查之前，不妨先详细了解一下图片的生命周期以及图片的托管位置。

映像生命周期

当您创建 Pod 时，kubelet 会收到 Pod 定义，其中包含映像的规范。kubelet 需要此映像，才能根据该映像运行容器。在拉取映像之前，kubelet 会检查容器运行时，以查看是否存在映像。kubelet 还会检查 pod 的映像拉取政策。如果映像不在容器运行时的缓存中，或者映像拉取政策要求这样做，则 kubelet 会指示容器运行时 (containerd) 从注册表中拉取指定映像。映像拉取失败会导致 pod 中的容器无法启动。

成功拉取映像后，容器运行时会解压缩映像，以便为容器创建只读基础文件系统。容器运行时会存储此映像，并且只要正在运行的容器引用该映像，该映像就会保留。如果没有任何正在运行的容器引用映像，则该映像将符合垃圾回收条件，并且 kubelet 最终会将其移除。

图片托管选项

我们建议您使用以下任一选项托管图片：

• Artifact Registry：Artifact Registry 是 Google 的全托管式软件包管理器。Artifact Registry 与其他 Google Cloud服务紧密集成，并提供精细的访问权限控制。如需了解详情，请参阅 Artifact Registry 文档中的使用容器映像。

• 自托管注册库：自托管注册库可让您拥有更大的控制权，但您也需要自行管理注册库。如果 Artifact Registry 无法满足您的特定合规性或安全需求，不妨考虑此选项。

诊断映像拉取失败

如需诊断映像拉取失败问题，请执行以下部分中详述的调查步骤：

1. 查看 Pod 状态和事件。
2. 了解状态含义。
3. 使用事件消息查找图片拉取失败的原因。
4. 查看 Logs Explorer 日志。

查看 Pod 状态和事件

为帮助您验证映像拉取是否失败，GKE 会为 Pod 记录以下状态：

• ImagePullBackOff
• ErrImagePull
• ImageInspectError
• InvalidImageName
• RegistryUnavailable
• SignatureValidationFailed

ImagePullBackOff 和 ErrImagePull 是其中最常见的状态。

除了这些状态之外，Kubernetes 事件还可帮助您查找映像拉取失败的原因。

如需确认您的映像拉取是否失败，请检查状态消息，然后选择以下选项之一来读取事件消息：

了解状态含义

如需更好地了解不同状态的含义，请参阅以下说明：

• ImagePullBackOff：kubelet 未能拉取映像，但会继续重试，每次重试的延迟（或后退）会增加，最长可达 5 分钟。
• ErrImagePull：映像拉取过程中的常规不可恢复错误。
• ImageInspectError：容器运行时在尝试检查容器映像时遇到问题。
• InvalidImageName：Pod 定义中指定的容器映像名称无效。
• RegistryUnavailable：无法访问注册表。这通常是网络连接问题。
• SignatureValidationFailed：无法验证容器映像的数字签名。

使用事件消息查找映像拉取失败的原因

下表列出了与图片拉取失败相关的事件消息，以及在您发现其中某条消息时应遵循的问题排查步骤。

与图片拉取失败相关的消息通常带有以下前缀：

Failed to pull image "IMAGE_ADDRESS": rpc error: code = CODE = failed to pull and unpack image "IMAGE_ADDRESS": failed to resolve reference "IMAGE_ADDRESS":

此消息包含以下值：

• IMAGE_ADDRESS：图片的完整地址。例如 us-west1-docker.pkg.dev/my-project/my-repo/test:staging。
• CODE：与日志消息关联的错误代码。例如 NotFound 或 Unknown。

某些导致映像拉取失败的原因没有相关的事件消息。如果您在下表中没有看到任何事件消息，但仍遇到图片提取问题，我们建议您继续阅读本页的其余内容。

查看 Logs Explorer 日志

如需检查历史映像拉取事件或将映像拉取失败与其他组件活动相关联，请使用 Logs Explorer 查看日志：

1. 在 Google Cloud 控制台中，转到日志浏览器页面。

   转到日志浏览器

2. 在查询窗格中，输入以下查询：

   log_id("events")
   resource.type="k8s_pod"
   resource.labels.cluster_name="CLUSTER_NAME"
   jsonPayload.message=~"Failed to pull image"
   

   将 CLUSTER_NAME 替换为出现映像拉取错误的 Pod 所运行的集群的名称。

3. 点击运行查询，然后查看结果。

调查身份验证设置

以下部分可帮助您验证 GKE 环境是否具有从代码库拉取映像的适当身份验证设置。

如需检查是否存在导致映像拉取问题的身份验证问题，请执行以下部分中详述的调查操作：

1. 验证对图片的访问权限。
2. 验证 imagePullSecret 配置和部署规范。
3. 验证节点对私有 Artifact Registry 制品库的访问范围
4. 验证 VPC Service Controls 设置以访问 Artifact Registry。

验证对图片的访问权限

如果您遇到 403 Forbidden 映像拉取错误，请验证所需组件是否可以访问容器映像。

验证和应用必要角色以授予所需访问权限的方法因存储图片的代码库类型而异。如需验证并授予访问权限，请选择以下选项之一：

验证 imagePullSecret 配置和部署规范

如果您使用 imagePullSecret，请确保您创建了一个用于存储用于拉取映像的身份验证凭据的 Secret，并且所有部署都指定了您定义的 Secret。如需了解详情，请参阅 Kubernetes 文档中的在 Pod 上指定 imagePullSecrets。

验证节点对私有 Artifact Registry 制品库的访问范围

如果您将容器映像存储在私有 Artifact Registry 代码库中，您的节点可能没有正确的访问范围。如果发生这种情况，您可能会注意到 401 Unauthorized 映像拉取错误。

如需验证访问权限范围并根据需要授予访问权限，请按以下步骤操作：

1. 确定运行 Pod 的节点：

   kubectl describe pod POD_NAME | grep "Node:"
   

   将 POD_NAME 替换为发生映像拉取失败的 Pod 的名称。

2. 验证您在上一步中确定的节点是否具有正确的存储范围：

   gcloud compute instances describe NODE_NAME \
       --zone="COMPUTE_ZONE \
       --format="flattened(serviceAccounts[].scopes)"
   

   替换以下内容：

   • NODE_NAME：您在上一步中标识的节点的名称。
   • COMPUTE_ZONE：节点所属的 Compute Engine 可用区。

   输出应至少包含以下一个访问权限范围：

   • serviceAccounts[0].scopes[0]: https://www.googleapis.com/auth/devstorage.read_only
   • serviceAccounts[0].scopes[0]: https://www.googleapis.com/auth/cloud-platform

   如果节点不包含以上范围之一，图片拉取将失败。

3. 使用足够的范围重新创建节点所属的节点池。 由于您无法修改现有节点，因此必须使用正确的范围重新创建节点。

   我们建议您使用 gke-default 范围创建节点池。此镜重提供对以下镜重的访问权限：

   • https://www.googleapis.com/auth/devstorage.read_only
   • https://www.googleapis.com/auth/logging.write
   • https://www.googleapis.com/auth/monitoring
   • https://www.googleapis.com/auth/service.management.readonly
   • https://www.googleapis.com/auth/servicecontrol
   • https://www.googleapis.com/auth/trace.append

   如果 gke-default 范围不适用，请向节点池授予 devstorage.read_only 范围，该范围仅允许访问读取数据。

   gke-default

   使用 gke-default 范围创建节点池：

   gcloud container node-pools create NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --zone=COMPUTE_ZONE \
       --scopes="gke-default"
   

   替换以下内容：

   • NODE_POOL_NAME：新节点池的名称。
   • CLUSTER_NAME：现有集群的名称。
   • COMPUTE_ZONE：新节点池应属于的 Compute Engine 可用区。

   devstorage.read_only

   使用 devstorage.read_only 范围创建节点池：

   gcloud container node-pools create NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --zone=COMPUTE_ZONE \
       --scopes="https://www.googleapis.com/auth/devstorage.read_only"
   

   替换以下内容：

   • NODE_POOL_NAME：新节点池的名称。
   • CLUSTER_NAME：现有集群的名称。
   • COMPUTE_ZONE：新节点池应属于的 Compute Engine 可用区。

验证 VPC Service Controls 设置以访问 Artifact Registry

如果您使用 VPC Service Controls，请确保服务边界允许访问 Artifact Registry。如需了解详情，请参阅 Artifact Registry 文档中的在服务边界内保护代码库。

调查网络连接

在拉取映像期间，网络连接可能会导致该过程无法完成。

如需检查网络连接问题是否导致了映像拉取问题，请执行以下部分中详述的调查：

1. 调查 DNS 解析。
2. 检查您的防火墙配置。
3. 调查外部注册表端点的互联网连接情况。
4. 调查与 Google API 的连接是否超时。

调查 DNS 解析

如果您看到 server misbehaving 映像拉取错误，则 DNS 解析可能是导致映像拉取失败的原因。

如需调查 DNS 解析问题，请尝试以下解决方案：

1. 排查元数据服务器问题。节点的元数据服务器会解析所有 DNS 查询。与此服务器相关的任何问题都可能会中断名称解析，阻止连接到代码库并导致映像拉取失败。
2. 如果您使用 Cloud DNS 进行 DNS 解析，请确保 Cloud DNS 代管的专用区域、转发区域、对等互连区域和响应政策已正确配置。这些方面出现的配置错误可能会干扰 DNS 解析。如需详细了解 Cloud DNS，请参阅使用 Cloud DNS for GKE。 如需有关如何在 GKE 中排查 Cloud DNS 问题的建议，请参阅在 GKE 中排查 Cloud DNS 问题。
3. 如果您使用 kube-dns 进行 DNS 解析，请确保它正常运行。如需有关排查 kube-dns 问题的建议，请参阅排查 GKE 中的 kube-dns 问题。
4. 如果集群的节点没有外部 IP 地址（如果您使用网络隔离，这种情况很常见），请在集群使用的子网上启用专用 Google 访问通道，并确保您满足网络要求。 如果您使用 Cloud NAT，Google Cloud 会自动启用专用 Google 访问通道。

调查防火墙配置

如果防火墙出现问题导致映像拉取失败，您可能会看到以下错误消息：

Failed to start Download and install k8s binaries and configurations

诊断防火墙问题

如果您使用的是标准集群，并且想要确认防火墙问题是否导致了图片拉取问题，请按以下步骤操作：

1. 使用 SSH 连接到出现问题的节点：

   gcloud compute ssh NODE_NAME --zone=ZONE_NAME
   

   替换以下内容：

   • NODE_NAME：节点的名称。
   • ZONE_NAME：节点的创建位置（Compute Engine 可用区）。

2. 将 kube-node-installation.service 和 kube-node-configuration.service 服务的最新日志发送到名为 kube-node-installation_status.txt 和 kube-node-configuration_status.txt 的文本文件：

   systemctl status kube-node-installation.service > kube-node-installation_status.txt
   systemctl status kube-node-configuration.service > kube-node-configuration_status.txt
   

   如果这些日志不包含映像提取失败时的信息，请生成日志的完整副本：

   sudo journalctl -u kube-node-installation.service > kube-node-installation_logs.txt
   sudo journalctl -u kube-node-configuration.service > kube-node-configuration_logs.txt
   

3. 查看 kube-node-installation_status.txt 和 kube-node-configuration_status.txt 文件的内容。如果您在输出中看到 i/o timeout，则表示问题可能出在防火墙上。

解决防火墙配置问题

如需解决防火墙问题，请尝试以下解决方案：

1. 找出并解决阻止网络流量的所有防火墙规则。例如，您可以设置一条规则来屏蔽对存储映像的注册表的流量。

   1. 访问 VPC 流日志：

      1. 在 Google Cloud 控制台中，转到日志浏览器页面。

         转到日志浏览器

      2. 在查询窗格中，输入以下查询：

         resource.type="gce_subnetwork"
         logName="projects/PROJECT_ID/logs/[compute.googleapis.com%2Fvpc_flows](http://compute.googleapis.com%2Fvpc_flows)"
         resource.labels.subnetwork_name="SUBNET_NAME",
         

         替换以下内容：

         • PROJECT_ID：您的 Google Cloud 项目的 ID。
         • SUBNET_NAME：子网的名称。

         如需了解详情，请参阅 VPC 文档中的通过查询访问流日志。

   2. 如果您发现任何防火墙规则阻止了所需流量，请更新这些规则。

2. 如果集群的节点没有外部 IP 地址（如果您使用网络隔离，这种情况很常见），请在集群使用的子网上启用专用 Google 访问通道，并确保您满足网络要求。 如果您使用 Cloud NAT，Google Cloud 会自动启用专用 Google 访问通道。

调查外部注册表端点的互联网连接情况

如果您的网络配置会将流量定向到外部注册表端点，则该端点可能无法连接到互联网。如果端点缺少访问权限，映像拉取可能会失败，并且您会看到 i/o timeout 映像拉取错误。

如需检查从外部注册库端点到注册库的网络连接，请使用 ping 或 traceroute：

ping REGISTRY_ENDPOINT

或

traceroute REGISTRY_ENDPOINT

将 REGISTRY_ENDPOINT 替换为代码库端点。此值可以是主机名或 IP 地址。

如果您发现连接存在错误，请检查 VPC 路由：

1. 在 Google Cloud 控制台中，前往路由。

   转到“路由”

2. 查看优先级列，确保优先级最高的路由指向有权访问注册表的来源。值越小，路由优先级越高。

调查与 Google API 的连接是否超时

如果您使用网络隔离，可能会遇到连接到 Google API 和服务超时的错误，导致 i/o timeout 映像拉取错误。

出现此错误是因为您的节点在尝试从注册表拉取映像时无法访问以下某个 API：

• containerregistry.googleapis.com
• artifactregistry.googleapis.com

为确保您能够连接到所需的 API，请尝试以下解决方案：

1. 启用专用 Google 访问通道。没有外部 IP 地址的节点需要专用 Google 访问通道才能访问 Google API 和服务的外部 IP 地址。
2. 使用受支持的网域。

3. 查看防火墙政策：

   1. 在 Google Cloud 控制台中，前往“防火墙政策”。

      前往“防火墙政策”

   2. 检查您是否有任何规则会阻止从端口 443 将出站 TCP 流量发送到 199.36.153.4/30、199.36.153.8/30 或您选择的网域为 Google API 和服务使用的任何IP 地址范围。IP 地址范围 199.36.153.4/30 和 199.36.153.8/30 分别用于专用 Google 访问通道和受限 Google 访问通道。端口 443 到这些范围的 TCP 流量用于访问 Google API 和服务。

      如果您发现任何此类规则，请创建出站防火墙规则以允许此类流量。

4. 如果您使用 Artifact Registry，请确保您的环境符合将 Artifact Registry 与网络隔离结合使用的要求。

5. 验证虚拟 IP 地址 (VIP) (199.36.153.4/30 或 199.36.153.8/30) 是否已配置 VPC 路由：

   1. 在 Google Cloud 控制台中，前往“VPC 网络”。

      转到 VPC 网络页面

   2. 在名称列中，点击默认。

   3. 在“VPC 网络详情”页面中，点击路由标签页。

   4. 查看路由表。

      如果您的 VPC 网络包含默认路由（目标 0.0.0.0/0 或 ::0/0），且该路由的下一个跃点是默认互联网网关（网络默认），请让 VIP 使用该路由访问 Google API 和服务。

      如果您已将默认路由替换为下一个跃点不是默认互联网网关的自定义路由，请使用自定义路由来满足 Google API 和服务的路由要求。

调查 kubelet 找不到映像的原因

如果 kubelet 找不到您的映像，您可能会看到 image not found 错误并遇到映像拉取失败问题。

如需帮助 kubelet 找到您的映像，请尝试以下解决方案：

1. 检查 Pod 的清单，确保映像名称和映像标记的拼写正确无误。任何拼写或格式错误都会导致图片拉取失败。
2. 验证映像是否仍存在于您存储它的注册表中。如果映像具有完整的注册表路径，请验证它是否存在于您使用的 Docker 注册表中。如果仅提供映像名称，请检查 Docker Hub 注册表。
3. 如果您的集群使用网络隔离，请尝试以下解决方案：
   1. 启用专用 Google 访问通道。
   2. 验证服务边界是否配置正确。

调查图片拉取超时或图片拉取速度缓慢的原因

如果您为 GKE 工作负载使用非常大的映像，映像拉取操作可能会超时并导致 context cancelled 错误。虽然图片没有定义的大小限制，但 context cancelled 错误通常表示图片大小是导致问题的原因。

您可能还会发现，图片拉取操作虽然不会失败，但所花时间比平时要长得多。如果您想了解常规映像拉取时间的基准值，请查看 Successfully pulled image 日志条目。例如，以下日志消息显示映像拉取花费了 30.313387996 秒：

Successfully pulled image "IMAGE_ADDRESS" in 30.313387996s.

超时和映像拉取缓慢有许多相同的原因。如需解决这些问题，请尝试以下解决方案：

1. 检查是否存在服务中断。如果您仅在特定时间段内发现此问题，请检查是否发生了 Google Cloud 服务中断。
2. 检查磁盘性能。磁盘 I/O 速度缓慢可能会增加映像拉取时间。考虑升级到包含 SSD 的永久性磁盘 (pd-ssd)，或使用更大的磁盘以提高性能。如需更多建议，请参阅排查磁盘性能问题。
3. 缩减图片大小。例如，您或许可以将部分数据从容器映像移至永久性卷。
4. 利用映像缓存缩短 Pod 启动时间。 GKE 会在节点上缓存图片。在拉取映像期间，容器运行时仅下载缓存中不存在的层。为了最大限度地提高此缓存机制的效率并尽可能缩短映像拉取时间，请构建 Dockerfile，将映像中经常更改的部分（例如应用代码）放置在文件末尾，并使用较小的映像基础。
5. 启用映像流式传输。此功能可以加快 pod 启动和映像下载速度。如需了解详情，请参阅使用映像流式传输拉取容器映像。
6. 确保默认服务账号具有必要的权限。修改分配给默认服务账号的角色可能会中断工作负载，包括映像拉取。如需更多建议，请参阅识别节点服务账号缺少关键权限的集群。
7. 检查代理配置。如果您的 GKE 集群和非 Google 管理的代码库之间存在代理，则可能会导致延迟。
8. 检查第三方软件。某些第三方软件可能会干扰图片拉取。调查最近安装的工具是否可能导致冲突。

验证映像清单是否使用了正确的架构

如果您尝试拉取的映像是为与节点池使用的计算机架构不同的架构构建的，则映像拉取将失败。

如需确认您的映像清单是否使用了正确的架构，请按以下步骤操作：

1. 如需确认您的映像使用的架构，请查看映像的清单。例如，如需查看 Docker 映像，请运行以下命令：

   docker manifest inspect --verbose IMAGE_NAME
   

   将 IMAGE_NAME 替换为您要查看的映像的名称。

   输出类似于以下内容：

   ...
   "Platform": {
             "architecture": "amd64",
             "os": "linux"
     }
   ...
   

   在此示例中，支持的架构为 amd64。

2. 查看节点池使用的机器类型：

   gcloud container node-pools list --cluster CLUSTER_NAME --location LOCATION
   

   替换以下内容：

   • CLUSTER_NAME：出现图片拉取错误的 Pod 所运行的集群的名称。
   • LOCATION：节点的创建Compute Engine 可用区或区域。例如 us-central1-a 或 us-central1。

   输出类似于以下内容：

   NAME: example-node-pool
   MACHINE_TYPE: e2-standard-2
   DISK_SIZE_GB: 100
   NODE_VERSION: 1.30.8-gke.1162000
   

   在此示例中，机器类型为 e2-standard-2。

3. 比较 architecture 和 MACHINE_TYPE 字段中的值，并确保这两个值兼容。例如，如果映像采用 amd64 架构，则与使用 e2-standard-2 作为机器类型的节点池兼容。但是，如果节点池使用 t2a-standard-1（基于 Arm 的机器类型），此机器类型会导致失败。

4. 如果映像的架构与节点池的机器类型不兼容，请重新构建映像以定位到所需的架构。

验证图片架构版本兼容性

将 containerd 2.0 与 v1 Docker 架构映像搭配使用会导致映像拉取失败，因为 containerd 2.0 移除了对在 GKE 1.33 中拉取 Docker Schema 1 映像的支持。如果此问题是导致映像拉取失败的原因，您可能会看到以下错误消息：

Failed to get converter for "IMAGE_ADDRESS": Pulling Schema 1 images have been deprecated and disabled by default since containerd v2.0. As a workaround you may set an environment variable `CONTAINERD_ENABLE_DEPRECATED_PULL_SCHEMA_1_IMAGE=1`, but this will be completely removed in containerd v2.1.

如需解决此问题，请按照从 Docker Schema 1 映像迁移中的说明，识别并迁移这些映像。

后续步骤

如果您需要其他帮助，请与 Cloud Customer Care 联系。