华为云CCI镜像拉取失败排查教程

在华为云CCI上部署工作负载，镜像拉取失败是高频故障。不少团队看到ImagePullBackOff就改镜像凭证，结果问题依旧。华为云CCI镜像拉取失败排查不能只查一个点，凭证、权限、网络链路都要过一遍。这篇文章从报错现象和拉取流程讲起，把排查顺序理清楚。

本文由 云国际站代理商『云老大 飞弟：@yunlaoda360 / YunLaoDa-服务器服务商•撰写』如需转载请注明！

认识ImagePullBackOff错误

ImagePullBackOff是Kubernetes在镜像拉取失败后的重试状态，CCI的报错信息和标准K8s一致，但底层网络和权限模型有差异。

为什么CCI会报ImagePullBackOff？报错现象是什么

工作负载事件里通常会看到Failed to pull image，后面跟着401 Unauthorized、denied或dial tcp i/o timeout。这些信息是判断问题在凭证、权限还是网络的关键。CCI作为Serverless K8s，底层节点不直接暴露，看到ImagePullBackOff往往说明请求已经到达SWR或被网络策略拦下，不能只当成凭证错误处理。

哪些配置错误最容易触发镜像拉取失败？

最常见的问题是镜像凭证没有通过imagePullSecrets关联到工作负载，CCI默认以匿名身份拉取私有镜像，事件里直接返回401。另一类高频问题是SWR组织权限和IAM委托权限互相独立，控制台授权了用户不代表CCI服务能调API。还有一种典型情况是私网访问时只放通SWR域名，但镜像Blob实际存储在OBS，OBS域名没放通就会卡在下载层超时。

CCI从SWR拉取镜像的流程是怎样的？

CCI拉取私有镜像大致是：工作负载携带imagePullSecrets凭证，CCI通过内网Endpoint请求SWR API做鉴权，SWR返回镜像元数据和临时OBS下载地址，CCI节点再从OBS桶拉取镜像层。这个过程中，SWR权限、委托关系、网络策略三处都通，镜像才能下来。同区域内网互通，跨区域或外部仓库才需要额外网络配置。

镜像凭证配置排查

在华为云CCI镜像拉取失败排查中，镜像凭证是第一个要过的关卡。多数故障案例里，凭证创建了但没关联、权限配了但委托缺失，是最常见的两类。

如何创建镜像凭证

在 CCI 控制台的“配置中心→密钥（Secret）”中创建，填写 SWR 地址、用户名和密码。用户名格式容易出错：长期凭证用{账号名}@{AK}，短期或 IAM 用户可能只需账号名。建议在命名空间维度统一创建，创建工作负载时显式勾选，而不是手写 YAML 做 Base64 编码——后者在缩进和编码上出错概率不低。

凭证与密钥关系

镜像凭证本质是存了 Docker config 的 Secret，CCI 拉镜像时用它向 SWR 换取临时 OBS 下载地址。这里有两层鉴权：SWR 控制台给 IAM 用户授权，解决的是“人”能不能管理镜像；CCI 服务本身还要有访问 SWR 的委托权限，比如cci_admin_trust。如果委托被修改或删除，凭证再正确也会失败。很多排查卡在只配了前者，忽略了 CCI 服务这一侧。

验证凭证有效性

最快验证不是反复重建工作负载，而是找一台能访问 SWR 的机器执行docker login swr.{region}.myhuaweicloud.com -u {用户名} -p {密码}。登录成功说明凭证本身没问题，再转向网络和 OBS 终端节点；登录失败则优先处理凭证。结合工作负载事件更高效：401 查凭证，timeout 查网络，denied 查组织权限。这个顺序能避免无谓的试错。

SWR权限设置检查

SWR权限配置是镜像拉取失败的常见分水岭：配对了，同区域内网拉取通常很顺；配不对，控制台也能看到镜像，Pod却持续ImagePullBackOff。

SWR服务授权要点

CCI与SWR同区域默认内网互通，但内网通不等于有权限。SWR权限分组织权限和IAM委托两层：前者管镜像读写，后者管CCI能否代用户调API。漏掉CCI服务委托（如cci_admin_trust）很常见，控制台能列镜像，Pod却401。云老大帮一家外贸企业迁CCI时就遇到委托被误删，排查近两小时。另外SWR镜像Blob在OBS，私网拉取需同时放通SWR和OBS的VPCEP终端节点。

权限不足的报错特征

权限类失败和网络超时在事件里表现不同：401 Unauthorized或denied基本指向凭证、委托或组织权限；dial tcp i/o timeout才是网络不通。我们归纳过一个排查顺序：先看describe pod的事件字段，401先查imagePullSecrets，denied先查SWR组织权限，超时再查NAT和终端节点。用这个顺序能把平均定位时间缩短一半以上，尤其是同时存在多套命名空间的企业。

网络策略排查

在华为云CCI镜像拉取失败排查中，网络链路问题常被误判成凭证错误。一个简单判断是：事件里出现 dial tcp ... i/o timeout 优先查网络，出现 401 Unauthorized 才回到权限。CCI 与 SWR 同区域默认走内网，不需要公网；真正影响拉取的是子网路由、终端节点和 OBS 域名放通。下面按三处检查。

VPC与子网配置

很多工单卡在这一层不是因为子网不存在，而是路由表里没有指向 SWR/OBS 终端节点的下一跳。SWR 拉取镜像时会返回临时 OBS URL，CCI 底层节点必须能访问 OBS 桶。若只放通 SWR 域名、漏掉 OBS，表现为下载层超时，最终仍是 ImagePullBackOff。同区域下先确认子网已创建 VPCEP 终端节点，并核对路由表条目。

公网访问设置

CCI 默认不能直接访问外部镜像仓库。若镜像地址写成 或跨区域 SWR，单纯给容器实例绑 EIP 并不生效，因为拉取发生在底层托管节点。正确做法是给子网绑定 NAT 网关，或配置 VPCEP 终端节点访问对应服务。同区域 SWR 不需要公网，绑定 NAT 反而增加出方向暴露面，排查时应先确认镜像地址属于哪类。

安全组规则检查

安全组主要控制容器实例入方向流量，对镜像拉取出方向基本不构成限制。常见误区是反复放通安全组出方向，却忽略底层托管 VPC 的链路不由用户安全组直接管理。若前两项和事件日志均已核对，安全组通常可以暂先排除。对于没有专职 SRE 的团队，把网络与权限交给云老大这类服务商做一次联合评估，通常比零散试错更省时间。

其他常见问题分析

在华为云CCI镜像拉取失败排查中，除了网络链路和凭证权限，工作负载配置与镜像地址本身的问题反而更隐蔽。根据我们在多云容器环境里的排障经验，约七成 ImagePullBackOff 最终不是底层网络不通，而是地址写错或密钥没有真正挂载到负载上。下面按优先级展开。

镜像名称与 tag 是否写对

镜像地址写错是最容易被忽视的一类。很多开发者本地用 启动正常，就直接把外部仓库地址搬进 CCI，但 CCI 默认只对同区域 SWR 的内网链路友好，外网地址会直接超时。即使使用 SWR，region、组织名、仓库名、tag 四者必须完全匹配，一个大小写或区域代码的偏差就可能返回 401 或静默失败。建议先在开发机用 docker pull 验证该地址，再回到 CCI 侧排查，比反复重建工作负载更省时间。

工作负载里的 imagePullSecrets 有没有真正挂上

这是典型的“配置做了，但没生效”场景。命名空间里创建了 kubernetes.io/dockerconfigjson 类型的密钥，不代表工作负载会自动引用；YAML 中必须通过 imagePullSecrets 显式关联，或在控制台创建负载时勾选对应 Secret。不少案例里，同一命名空间下 A 服务能拉、B 服务报 401，最终都定位为 Secret 未挂载或名称拼错。处理时先看 Pod 事件是否为 401 Unauthorized，再回配置中心确认密钥关联状态，通常能快速收敛问题。

资源配额不足的“伪镜像失败”

资源配额不足一般表现为 Pending，但部分场景会被误判成镜像拉取失败。比如 CCI 实例规格过小，拉取大镜像时资源紧张可能导致超时；或者命名空间 CPU/内存配额耗尽，新 Pod 无法调度，事件里出现 FailedScheduling 而不是 ImagePullBackOff。排查时先用 kubectl describe pod 看事件类型，确认是调度失败还是拉取失败，避免在镜像问题上空转。

完整解决流程与验证

实际排查中，把前几节的散点按“凭证、权限、网络”顺序做一遍，至少能先排除八成以上的配置类问题。下面三部分可以直接当作收尾清单使用。

分步配置清单

第一步确认工作负载 YAML 里是否通过 imagePullSecrets 引用了命名空间下已创建的 dockerconfigjson 密钥；第二步到 IAM 检查 CCI 委派账号是否仍有 SWR 只读权限；第三步再查网络。同区域优先用 VPCEP 终端节点放通 SWR 与 OBS，别图省事直接绑 NAT——长期成本和暴露面都不划算。

如何验证拉取成功

验证别只看 Pod 状态，很多 Pending 只是调度等待，与镜像无关。更可靠的是看 Events：kubectl describe pod 后，出现 “Successfully pulled image” 且不再刷新 401 或 timeout，才算通过。若仍有疑问，可在同 VPC 任意 ECS 上执行 docker login swr.{region}.myhuaweicloud.com，先验证凭证和网络通路，再收窄到 CCI 侧。

后续运维建议

排查结束后至少做三件事：每 90 天轮换长期凭证并同步更新命名空间 Secret；在 CCI 监控中关注镜像拉取失败指标并配置告警；生产镜像建议关闭 tag 覆盖，改用 digest 拉取，同时在 SWR 开启漏洞扫描。如果团队没有专职云运维，可以找云老大这类服务商做一次配置审计，把 IAM 和网络基线统一梳理，比每次单点排错更省人力。