机制定位
拉取私有仓库镜像需要凭据，凭据存在 docker-registry 类型（即 kubernetes.io/dockerconfigjson）的 Secret 里，由 kubelet 在拉取镜像时使用。适用平台是 Kubernetes。凭据有两处引用方式：写在工作负载 Pod 模板的 imagePullSecrets 上，或绑到 ServiceAccount 上让该账号下的 Pod 自动继承。前者便于逐个工作负载控制，后者适合整命名空间统一生效。
基本信息
| 适用平台 | Kubernetes，Secret 类型 kubernetes.io/dockerconfigjson |
|---|---|
| 创建命令 | kubectl create secret docker-registry <名称> --docker-server/--docker-username/--docker-password |
| 引用方式 | Pod 模板的 spec.imagePullSecrets，或 ServiceAccount 的 imagePullSecrets |
| 作用范围 | Secret 为命名空间级，每个命名空间需各建一份或做同步 |
典型使用场景
- 拉取企业私有仓库镜像：CI 推送后由 kubelet 凭凭据拉取
- 多命名空间隔离：每个命名空间各建一份凭据并绑定到该空间的 ServiceAccount
- 临时排查镜像拉取失败：用同一凭据在节点上手工验证仓库可达性
- Token 轮换：更新 Secret 内容后，新创建的 Pod 使用新凭据
- 多仓库并存：为不同仓库分别创建命名清晰的凭据对象
创建与引用
创建与引用
kubectl create secret docker-registry regcred -n prod \
--docker-server=registry.example.com \
--docker-username=robot-ci \
--docker-password=<token> \
--docker-email=ci@example.com
kubectl patch deploy web -n prod --type merge \
-p '{"spec":{"template":{"spec":{"imagePullSecrets":[{"name":"regcred"}]}}}}'
kubectl patch sa default -n prod --type merge -p '{"imagePullSecrets":[{"name":"regcred"}]}' # 或绑到 ServiceAccount排查拉取失败
排查拉取失败
kubectl describe pod web-x | grep -A5 -i -E 'pull|failed' # 事件里的原始报错
kubectl get secret regcred -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d | head -c 200
kubectl get deploy web -o jsonpath='{.spec.template.spec.imagePullSecrets}'
kubectl get sa default -o jsonpath='{.imagePullSecrets}'报错与原因
| 事件提示 | 原因 | 处理 |
|---|---|---|
| pull access denied / unauthorized | 凭据无效或无权访问该仓库路径 | 核对用户名密码与仓库权限 |
| manifest unknown | 镜像名或 tag 不存在 | 核对 tag 与仓库项目名 |
| i/o timeout | 节点到仓库网络不通 | 查节点出网与仓库白名单 |
| ImagePullBackOff | 综合失败状态 | 先看 Events 原文再定位 |
多命名空间各自维护一份凭据；也可以把 Secret 绑到工作负载使用的 ServiceAccount 上，让该命名空间的新 Pod 自动继承。
已有本地镜像缓存的节点不会立刻暴露凭据失效问题，因此轮换 Token 后务必在无缓存的节点或新节点上验证一次。
落地建议
- 按仓库分别建凭据对象：一个 Secret 只对应一个 server 地址，镜像来源多时命名要能一眼看出用途
- 优先绑到 ServiceAccount：命名空间内所有工作负载自动继承，减少逐个 Deployment 配置的遗漏
- 轮换后用零缓存节点验证：老节点有镜像缓存，凭据失效不一定立刻暴露
- 把凭据更新纳入发布流程：Token 有有效期，过期时间要有人盯，避免扩容当天才发现拉不动