RUNBOOK / Kubernetes
Kubernetes ImagePullBackOff：私有 Registry 凭据与命名空间
Pod 拉取私有镜像失败，describe 中出现 ImagePullBackOff、鉴权失败或找不到 imagePullSecrets。
故障现象与判断依据
最可能原因
Kubernetes 要求 Pod 引用的 imagePullSecrets 位于同一命名空间；先验证镜像地址、Secret 名称和 Pod 规范，再处理 Registry 凭据。
LOGapiVersion: v1
kind: Pod
spec:
containers:
- image: <your-private-image>
imagePullSecrets:
- name: regcred安全诊断
以下命令用于读取状态、验证解析或复现请求；先确认目标主机、权限与影响范围。命令中的占位符必须替换为当前环境的实际值。
READ / VERIFYkubectl describe pod <pod> -n <namespace>
kubectl get secret regcred -n <namespace>
# 仅使用团队批准的 Registry 凭据创建指定命名空间 Secret
kubectl create secret docker-registry regcred -n <namespace> --docker-server=<registry> --docker-username=<user> --docker-password=<token>推荐修复步骤
- 1执行 kubectl describe pod <pod> -n <namespace>，记录 Events 中的镜像和鉴权阶段。
- 2执行 kubectl get secret regcred -n <namespace>，确认 Pod 所在命名空间中存在同名 Secret。
- 3按 Registry 官方凭据和 Kubernetes 文档创建或更新指定命名空间的 Secret，再重新创建或滚动更新工作负载。
验证、限制与回滚
修复后的验证
kubectl get pod -n <namespace> 显示容器已创建；kubectl describe pod 的 Events 不再新增镜像拉取错误。
风险提示与回滚
不要以关闭证书校验、删除全部缓存、无限重试、关闭防火墙或放宽到 chmod 777 来替代根因定位。任何配置变更前先保留原文件和校验结果；若验证失败，恢复该备份并重新采集日志。
可信来源与适用边界
参考来源Pull an Image from a Private Registry | Kubernetes ↗
imagePullSecrets references a Secret in the Pod namespace 此页将环境级案例与本 Runbook 的检查步骤分开呈现，不能把示例日志当作当前服务器的真实事件。