Debian 上 Kubernetes 镜像拉取失败的定位与修复
一、快速定位
- 查看具体错误原因：
- 查看 Pod 事件与状态：kubectl describe pod -n ；若镜像不存在或仓库无权限，常见为 ErrImagePull/ImagePullBackOff。
- 查看集群事件时间线：kubectl get events --sort-by=.metadata.creationTimestamp。
- 查看节点与 kubelet 日志：kubectl get nodes；journalctl -u kubelet -xe。
- 在节点上用容器运行时手动拉取验证：
- containerd：crictl pull :
- Docker：docker pull :
- 若使用私有仓库，确认是否已创建并绑定 imagePullSecret。
二、常见原因与对应修复
- 镜像名称或标签错误
- 现象：Events 报 “image not found”“manifest unknown”等。
- 处理：核对 image 字段与 tag；在节点上先 docker/crictl pull 验证；必要时修正 YAML 中的镜像名与 tag。
- 私有仓库未认证
- 现象：Events 报 “pull access denied”“unauthorized”。
- 处理：创建 Secret 并在 Pod/ServiceAccount 上引用：
- kubectl create secret docker-registry regcred --docker-server= --docker-username= --docker-password= --docker-email=
- 在 Pod spec.imagePullSecrets 或 ServiceAccount 中挂载该 Secret。
- 国内网络访问官方仓库慢或失败
- 现象：拉取超时、速度极慢。
- 处理：
- 初始化时指定国内镜像仓库：kubeadm init --image-repository=registry.aliyuncs.com/google_containers …
- 或提前在各节点拉取并重新打标签（示例，按实际版本替换）：
- crictl pull registry.aliyuncs.com/google_containers/kube-apiserver:v1.28.0
- crictl tag registry.aliyuncs.com/google_containers/kube-apiserver:v1.28.0 k8s.gcr.io/kube-apiserver:v1.28.0
- 其他组件同理（kube-controller-manager、kube-scheduler、kube-proxy、pause、etcd、coredns）。
- 镜像拉取策略导致反复拉取
- 现象：即使本地已有镜像仍反复尝试远程拉取。
- 处理：在容器 spec 中设置 imagePullPolicy: IfNotPresent（或 Never，仅离线场景）。
- containerd 配置不当（pause 镜像不匹配）
- 现象：创建 sandbox 失败，提示拉取 sandbox 镜像失败。
- 处理：检查 /etc/containerd/config.toml 中的 sandbox_image 与集群所需一致（如 k8s.gcr.io/pause:3.x），修改后重启 containerd：systemctl restart containerd。
- 节点网络与防火墙限制
- 现象：节点能解析域名但无法建立连接，或拉取超时。
- 处理：确保节点可访问镜像仓库域名/IP；如使用 UFW，放行关键端口（示例）：sudo ufw allow 6443,2379,2380,10250,10251,10252,10255/tcp；如使用 firewalld/iptables，做等价放行。
三、kubeadm 初始化阶段的镜像拉取失败处理
- 使用国内镜像仓库一键初始化（示例）：
- kubeadm init
–apiserver-advertise-address=<本机IP>
–pod-network-cidr=10.244.0.0/16
–image-repository=registry.aliyuncs.com/google_containers
- 若仍失败：
- 预先在各节点用 crictl/docker 拉取并打回官方仓库标签（按 kubeadm 所需版本），再执行 kubeadm init。
- 检查 kubelet 与容器运行时状态：systemctl status kubelet；journalctl -u kubelet -xe；确认 /etc/containerd/config.toml 的 sandbox_image 正确并已生效。
四、仍未解决时建议准备的关键信息
- kubeadm init 的完整输出与关键报错片段。
- 节点日志：journalctl -u kubelet -xe 的最后 100 行。
- 集群状态：kubectl get nodes -o wide；kubectl get pods -A -o wide。
- 系统信息：uname -a、lsb_release -a、free -m、df -h、ip a、sudo ufw status 或防火墙规则。
- 组件版本：kubelet --version、crictl version 或 docker version。