4. 常见故障现象分类：ImagePullBackOff、ErrImagePull、认证失败、超时、权限不足等典型错误信息解读

镜像拉取认证故障在 Kubernetes 集群中表现为几种典型的 Pod 状态和错误事件。准确识别这些错误信息是快速定位问题的第一步。本章将系统梳理最常见的故障现象，并解读其背后的根因。

4.1 核心故障现象总览

以下表格列出了 Kubernetes 中与镜像拉取认证相关的五种主要故障现象、对应的 Pod 状态、典型事件及常见根因：

4.2 故障现象详解与错误信息解读

4.2.1 ImagePullBackOff

状态特征： Pod 无法启动，kubelet 持续尝试拉取镜像，每次失败后等待时间指数级增长（BackOff）。

典型错误信息：

  Normal   Pulling    5m (x4 over 7m)    kubelet            Pulling image "myregistry.example.com/app:v1.0"
  Warning  Failed     5m (x4 over 7m)    kubelet            Failed to pull image "myregistry.example.com/app:v1.0": rpc error: code = Unknown desc = Error response from daemon: manifest for myregistry.example.com/app:v1.0 not found: manifest unknown: manifest unknown
  Warning  BackOff    4m (x7 over 7m)    kubelet            Back-off pulling image "myregistry.example.com/app:v1.0"

解读： 此例中错误为“manifest unknown”，表明镜像标签不存在或镜像已被删除，而非认证问题。但 ImagePullBackOff 也可能是认证失败、网络超时等问题的最终表现。

4.2.2 ErrImagePull

状态特征： 通常作为 ImagePullBackOff 的前置状态出现，表示 kubelet 在尝试拉取镜像时立即遇到了错误。

典型错误信息：

  Warning  Failed     1s                kubelet            Failed to pull image "private.registry.com/backend:latest": rpc error: code = Unknown desc = Error response from daemon: pull access denied for private.registry.com/backend, repository does not exist or may require 'docker login': denied: requested access to the resource is denied

解读： 错误信息明确提示“pull access denied”和“denied: requested access to the resource is denied”，这直接指向认证或权限问题。

4.2.3 认证失败

状态特征： Pod 事件中出现 unauthorized 或 authentication required 关键字。

典型错误信息：

  Warning  Failed     10s               kubelet            Failed to pull image "registry.example.com/private-image:1.0": rpc error: code = Unknown desc = Error response from daemon: unauthorized: authentication required

解读： 此错误明确表示镜像仓库要求认证，但 kubelet 未提供有效的凭据。常见原因包括：

• Pod 的 spec.imagePullSecrets 未配置。
• 引用的 Secret 不存在或命名空间错误。
• Secret 中的 .dockerconfigjson 内容格式错误或凭据已过期。

4.2.4 超时

状态特征： Pod 事件中出现 context deadline exceeded、TLS handshake timeout 或 i/o timeout。

典型错误信息：

  Warning  Failed     2m                kubelet            Failed to pull image "gcr.io/my-project/my-app:latest": rpc error: code = DeadlineExceeded desc = context deadline exceeded

解读： 超时通常与网络相关，而非直接由 Secrets 引起。但若镜像仓库需要认证，且认证过程因网络问题（如 DNS 解析慢、防火墙阻断）而超时，也会表现为超时错误。需要区分是网络层问题还是认证链路问题。

4.2.5 权限不足

状态特征： 错误信息中包含 denied、forbidden 或 access denied。

典型错误信息：

  Warning  Failed     30s               kubelet            Failed to pull image "myprivaterepo.azurecr.io/production-app:2.0": rpc error: code = Unknown desc = Error response from daemon: denied: requested access to the resource is denied

解读： 与“认证失败”不同，权限不足意味着凭据本身是有效的（Secret 存在且格式正确），但该凭据对应的用户或服务主体没有拉取目标镜像的权限。常见于：

• 镜像仓库的访问控制列表（ACL）未授权该用户。
• 使用了过期的 或已撤销的访问密钥。
• 在 Harbor 等企业级仓库中，项目权限配置错误。

4.3 故障现象与 Secrets 关联性分析

以下 SVG 图展示了从 Pod 创建到镜像拉取失败的过程中，Secrets 相关故障的决策路径：

4.4 故障现象快速定位表

以下表格帮助运维人员根据 Pod Events 中的关键字快速定位故障类型：

4.5 典型错误信息与 Secrets 关联案例

以下通过两个典型场景，展示错误信息与 Secrets 配置的对应关系：

场景一：Secret 未配置

错误事件：

  Warning  Failed     1m                kubelet            Failed to pull image "registry.example.com/private-image:1.0": rpc error: code = Unknown desc = Error response from daemon: unauthorized: authentication required

分析： 错误信息明确要求认证。检查 Pod YAML 发现 spec.imagePullSecrets 字段缺失。解决方案：创建 Secret 并在 Pod 中引用。

场景二：Secret 凭据权限不足

错误事件：

  Warning  Failed     30s               kubelet            Failed to pull image "myprivaterepo.azurecr.io/production-app:2.0": rpc error: code = Unknown desc = Error response from daemon: denied: requested access to the resource is denied

分析： Secret 存在且格式正确，但凭据对应的服务主体没有拉取 production-app 镜像的权限。解决方案：在 Azure Container Registry 的 RBAC 中授予 AcrPull 角色。

4.6 故障排查优先级建议

当遇到镜像拉取失败时，建议按以下优先级顺序排查：

1. 检查 Pod Events：使用 kubectl describe pod 获取具体错误信息。
2. 确认 Secret 是否存在：kubectl get secret -n <namespace>。
3. 验证 Secret 内容：kubectl get secret <secret-name> -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d。
4. 测试凭据有效性：在集群节点或本地使用 docker login 测试。
5. 检查网络与仓库可达性：curl -v https://registry.example.com/v2/。
6. 确认镜像标签与仓库地址：确保镜像名称和标签拼写正确。