1. 问题现象与初步诊断当你兴冲冲地部署完Kubernetes集群满心期待地输入kubectl get pods -n kube-system命令时却发现calico和coredns这两个关键组件全都卡在Pending状态节点状态也持续显示NotReady这时候的心情就像煮熟的鸭子飞走了——既着急又无奈。这种场景我在帮客户部署集群时遇到过不下二十次最常见的元凶就是镜像拉取失败。怎么快速确认问题根源老司机都会用这个黄金命令kubectl -n kube-system describe pod calico-kube-controllers-xxxxxx在Events部分如果你看到类似Failed to pull image或ImagePullBackOff的报错那基本可以锁定是镜像仓库访问问题。我遇到过最典型的情况是明明配置了国内镜像加速器但calico镜像还是死活拉不下来。这时候别急着砸键盘先检查下你的/etc/docker/daemon.json{ registry-mirrors: [ https://docker.m.daocloud.io, https://p5lmkba8.mirror.aliyuncs.com ] }注意很多新手会忽略一个关键点阿里云等国内镜像源现在大多需要企业认证才能使用个人开发者直接配置反而会导致拉取失败。去年我就帮一个创业团队排查过这个问题他们折腾了三小时没解决最后发现是镜像源权限问题。2. 网络环境深度排查当基础镜像源配置无效时我们需要像侦探一样层层深入。首先用这个命令检查节点网络连通性curl -v https://registry-1.docker.io/v2/如果卡在TCP连接阶段说明节点根本访问不了Docker Hub。这时候要分两种情况处理情况一集群节点有外网访问权限但速度慢测试不同镜像源响应速度time docker pull docker.m.daocloud.io/calico/cni:v3.25.0 time docker pull quay.io/calico/cni:v3.25.0我实测发现有时官方quay.io反而比国内镜像更快情况二完全无法访问外网常见于金融、政务云环境需要搭建本地镜像仓库docker run -d -p 5000:5000 --restart always --name registry registry:2然后手动导入离线镜像包docker save calico/cni:v3.25.0 calico-cni.tar docker load calico-cni.tar docker tag calico/cni:v3.25.0 localhost:5000/calico-cni:v3.25.0 docker push localhost:5000/calico-cni:v3.25.03. 代理配置实战技巧在某些特殊网络环境下配置代理可能是最直接的解决方案。但这里有个坑我踩过三次——Kubernetes组件对代理的敏感度不同。正确的配置姿势应该是先测试宿主机代理有效性export http_proxyhttp://your_proxy_ip:port curl -v https://www.google.com然后分层次配置Docker层代理修改/etc/systemd/system/docker.service.d/http-proxy.conf[Service] EnvironmentHTTP_PROXYhttp://proxy_ip:port EnvironmentNO_PROXYlocalhost,127.0.0.1,10.0.0.0/8Kubelet层代理编辑/etc/default/kubeletKUBELET_EXTRA_ARGS--http-proxyhttp://proxy_ip:port特别注意no_proxy配置必须包含所有节点IPPod CIDR默认10.244.0.0/16Service CIDR默认10.96.0.0/12 否则你会遇到更诡异的集群内部通信问题4. 镜像预加载与参数调优当网络条件实在恶劣时我常用的杀手锏是手动预加载镜像。具体操作流程找台能上网的机器拉取镜像docker pull calico/cni:v3.25.0 docker pull calico/node:v3.25.0打包传输到集群节点docker save calico/cni:v3.25.0 calico-cni.tar scp calico-cni.tar node1:/tmp/在目标节点加载镜像docker load /tmp/calico-cni.tar但这里有个高级技巧修改Calico的DaemonSet配置添加imagePullPolicy字段spec: template: spec: containers: - name: calico-node image: calico/node:v3.25.0 imagePullPolicy: IfNotPresent这个配置能避免kubelet重复尝试拉取镜像节省大量等待时间。对于拉取超时问题可以调整kubelet的启动参数--image-pull-progress-deadline5m --runtime-request-timeout10m这两个参数我建议在网络条件差的环境适当调大避免因超时导致Pod被误杀。5. 验证与故障回滚完成所有配置后建议按照这个检查清单逐步验证检查Pod状态watch kubectl get pods -n kube-system查看calico-node日志kubectl logs -n kube-system calico-node-xxxxx -c calico-node验证网络插件健康状态kubectl get felixconfigurations.crd.projectcalico.org -o yaml如果出现问题需要回滚记住这个万能命令组合kubectl delete -f calico.yaml systemctl restart kubelet iptables -F iptables -t nat -F这个组合拳能清理大多数Calico安装残留。去年在某次生产环境部署中这个技巧帮我节省了两小时的排查时间。最后提醒大家Calico版本与Kubernetes版本存在兼容性矩阵安装前务必查看官方文档。我见过最惨的案例是某团队用了最新版Calico搭配旧版K8s导致整个集群网络瘫痪。
从Pending到Running：Calico网络组件镜像拉取故障的深度排查与实战解决
发布时间：2026/7/14 1:18:24
1. 问题现象与初步诊断当你兴冲冲地部署完Kubernetes集群满心期待地输入kubectl get pods -n kube-system命令时却发现calico和coredns这两个关键组件全都卡在Pending状态节点状态也持续显示NotReady这时候的心情就像煮熟的鸭子飞走了——既着急又无奈。这种场景我在帮客户部署集群时遇到过不下二十次最常见的元凶就是镜像拉取失败。怎么快速确认问题根源老司机都会用这个黄金命令kubectl -n kube-system describe pod calico-kube-controllers-xxxxxx在Events部分如果你看到类似Failed to pull image或ImagePullBackOff的报错那基本可以锁定是镜像仓库访问问题。我遇到过最典型的情况是明明配置了国内镜像加速器但calico镜像还是死活拉不下来。这时候别急着砸键盘先检查下你的/etc/docker/daemon.json{ registry-mirrors: [ https://docker.m.daocloud.io, https://p5lmkba8.mirror.aliyuncs.com ] }注意很多新手会忽略一个关键点阿里云等国内镜像源现在大多需要企业认证才能使用个人开发者直接配置反而会导致拉取失败。去年我就帮一个创业团队排查过这个问题他们折腾了三小时没解决最后发现是镜像源权限问题。2. 网络环境深度排查当基础镜像源配置无效时我们需要像侦探一样层层深入。首先用这个命令检查节点网络连通性curl -v https://registry-1.docker.io/v2/如果卡在TCP连接阶段说明节点根本访问不了Docker Hub。这时候要分两种情况处理情况一集群节点有外网访问权限但速度慢测试不同镜像源响应速度time docker pull docker.m.daocloud.io/calico/cni:v3.25.0 time docker pull quay.io/calico/cni:v3.25.0我实测发现有时官方quay.io反而比国内镜像更快情况二完全无法访问外网常见于金融、政务云环境需要搭建本地镜像仓库docker run -d -p 5000:5000 --restart always --name registry registry:2然后手动导入离线镜像包docker save calico/cni:v3.25.0 calico-cni.tar docker load calico-cni.tar docker tag calico/cni:v3.25.0 localhost:5000/calico-cni:v3.25.0 docker push localhost:5000/calico-cni:v3.25.03. 代理配置实战技巧在某些特殊网络环境下配置代理可能是最直接的解决方案。但这里有个坑我踩过三次——Kubernetes组件对代理的敏感度不同。正确的配置姿势应该是先测试宿主机代理有效性export http_proxyhttp://your_proxy_ip:port curl -v https://www.google.com然后分层次配置Docker层代理修改/etc/systemd/system/docker.service.d/http-proxy.conf[Service] EnvironmentHTTP_PROXYhttp://proxy_ip:port EnvironmentNO_PROXYlocalhost,127.0.0.1,10.0.0.0/8Kubelet层代理编辑/etc/default/kubeletKUBELET_EXTRA_ARGS--http-proxyhttp://proxy_ip:port特别注意no_proxy配置必须包含所有节点IPPod CIDR默认10.244.0.0/16Service CIDR默认10.96.0.0/12 否则你会遇到更诡异的集群内部通信问题4. 镜像预加载与参数调优当网络条件实在恶劣时我常用的杀手锏是手动预加载镜像。具体操作流程找台能上网的机器拉取镜像docker pull calico/cni:v3.25.0 docker pull calico/node:v3.25.0打包传输到集群节点docker save calico/cni:v3.25.0 calico-cni.tar scp calico-cni.tar node1:/tmp/在目标节点加载镜像docker load /tmp/calico-cni.tar但这里有个高级技巧修改Calico的DaemonSet配置添加imagePullPolicy字段spec: template: spec: containers: - name: calico-node image: calico/node:v3.25.0 imagePullPolicy: IfNotPresent这个配置能避免kubelet重复尝试拉取镜像节省大量等待时间。对于拉取超时问题可以调整kubelet的启动参数--image-pull-progress-deadline5m --runtime-request-timeout10m这两个参数我建议在网络条件差的环境适当调大避免因超时导致Pod被误杀。5. 验证与故障回滚完成所有配置后建议按照这个检查清单逐步验证检查Pod状态watch kubectl get pods -n kube-system查看calico-node日志kubectl logs -n kube-system calico-node-xxxxx -c calico-node验证网络插件健康状态kubectl get felixconfigurations.crd.projectcalico.org -o yaml如果出现问题需要回滚记住这个万能命令组合kubectl delete -f calico.yaml systemctl restart kubelet iptables -F iptables -t nat -F这个组合拳能清理大多数Calico安装残留。去年在某次生产环境部署中这个技巧帮我节省了两小时的排查时间。最后提醒大家Calico版本与Kubernetes版本存在兼容性矩阵安装前务必查看官方文档。我见过最惨的案例是某团队用了最新版Calico搭配旧版K8s导致整个集群网络瘫痪。
)
