当前位置：首页 > news >正文

K8s 部署 calico 网络插件时拉取不到镜像怎么办？

news 2026/5/9 6:27:19

遇到 Calico 镜像拉取失败，最稳妥的办法是修改部署清单中的镜像地址为国内可访问的仓库，或者在容器运行时层面配置镜像加速，具体取决于你使用的是 Docker 还是 Containerd 以及能否修改 YAML 文件。

先说结论：优先检查容器运行时配置，若无效则直接替换 YAML 中的镜像地址。

适合：Kubernetes 集群初始化阶段或网络插件未就绪场景
先准备：确认节点容器运行时类型（Docker 或 Containerd）及当前网络连通性
验收：通过 kubectl get pods -n kube-system 确认 Pod 状态为 Running

命令速用版

如果是 Docker 运行时，可尝试配置 daemon.json 加速：

sudo tee /etc/docker/daemon.json <<-'EOF'
{"registry-mirrors": ["https://docker.m.daocloud.io", "https://registry.aliyuncs.com"]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

如果是直接部署 Calico，修改 yaml 中的 image 字段：

# 原地址
docker.io/calico/cni:v3.26.1
# 替换为国内源示例
docker.m.daocloud.io/calico/cni:v3.26.1

为什么会这样

Calico 官方镜像默认托管在 docker.io 或 quay.io，在国内网络环境下，这些仓库的访问稳定性较差，容易出现连接超时或 DNS 解析失败。此外，Kubernetes 核心组件可以通过 kubeadm 参数指定镜像源，但 Calico 这类第三方插件的 YAML 清单中镜像地址通常是硬编码的，不会自动继承集群的全局镜像配置。

分步处理

1. 确认报错信息

使用以下命令查看 Pod 详细状态，确认是 ImagePullBackOff 还是 ErrImagePull：

kubectl describe pod <calico-pod-name> -n kube-system

2. 选择解决方案

方案 A：配置容器运行时镜像加速（适合批量拉取）

对于 Docker，修改 /etc/docker/daemon.json；对于 Containerd，修改 /etc/containerd/config.toml 中的 registry.mirrors 配置。配置完成后需重启容器运行时服务。

方案 B：修改 Calico 部署清单（适合单次部署）

下载 calico.yaml 文件，搜索 image 关键字，将 docker.io 或 quay.io 开头的地址替换为国内镜像仓库地址。注意保持版本号一致。

3. 重新应用配置

如果修改了 YAML，使用 kubectl apply -f calico.yaml 重新部署。如果修改了运行时配置，删除失败的 Pod 让其重建：

kubectl delete pod <calico-pod-name> -n kube-system

怎么验证是否生效

观察 Pod 状态是否变为 Running，并检查事件日志中不再有拉取失败记录：

kubectl get pods -n kube-system -o wide
kubectl describe pod <calico-pod-name> -n kube-system | grep -A 5 Events

也可以在节点上直接查看镜像是否已存在：

docker images | grep calico
# 或
crictl images | grep calico

常见坑

容器运行时混淆：Kubernetes 1.24 后默认使用 Containerd，其配置文件和重启方式与 Docker 不同，配置 daemon.json 对 Containerd 无效。
镜像标签不存在：替换镜像地址时，需确保目标仓库中存在相同的版本号标签，否则会出现 manifest unknown 错误。
版本兼容性：部分 Calico 新版本（如 3.27）可能存在基础镜像兼容性问题，若遇到段错误可尝试回退至稳定版本（如 3.26.4）。
网络插件依赖：在 Calico 启动前，节点间网络需互通，防火墙规则可能拦截 BGP 或 IPIP 流量。