Kubernetes 1.28集群Flannel网络配置避坑指南：解决ImagePullBackOff与Harbor私有仓库配置
Kubernetes 1.28集群Flannel网络配置实战：从ImagePullBackOff到Harbor私有仓库的完整解决方案
当你在国内环境部署Kubernetes 1.28集群时，Flannel网络插件的配置往往会遇到镜像拉取失败的问题。这不仅仅是简单的网络连接问题，更涉及到容器运行时变更、镜像仓库配置等一系列技术细节。本文将带你深入剖析问题本质，并提供两种切实可行的解决方案。
1. 问题诊断与核心原因分析
使用kubectl describe pod命令查看Flannel Pod状态时，最常见的错误就是ImagePullBackOff。这通常表现为Pod始终处于Pending状态，事件日志中明确提示无法拉取flannel/flannel或flannel/flannel-cni-plugin镜像。
根本原因有三点：
- 国内网络限制：Flannel官方镜像托管在DockerHub等国外平台，国内直接访问速度极慢或完全不可达
- 容器运行时变更：Kubernetes 1.24+版本移除了dockershim，默认使用containerd作为容器运行时
- 镜像拉取策略：默认的
IfNotPresent策略在本地没有镜像时会尝试从远程仓库拉取
通过以下命令可以快速确认问题：
kubectl get pods -n kube-flannel kubectl describe pod <flannel-pod-name> -n kube-flannel2. 解决方案一：离线镜像本地导入
对于无法访问外网或临时测试环境，离线导入镜像是快速解决问题的有效方法。以下是详细操作步骤：
2.1 获取离线镜像包
首先需要获取以下两个核心镜像的离线压缩包：
flannel/flannel:v0.25.1flannel/flannel-cni-plugin:v1.4.0-flannel1
可以通过以下方式获取：
- 从能访问外网的机器使用
docker pull下载后导出 - 从第三方镜像源下载（如阿里云镜像仓库）
- 使用已导出的tar包（需确保版本匹配）
2.2 镜像导入containerd
由于Kubernetes 1.28默认使用containerd，需要特别注意导入到正确的命名空间：
# 将镜像导入k8s.io命名空间 ctr -n k8s.io images import flannel-flannel-v0.25.1-amd64.tar ctr -n k8s.io images import flannel-flannel-cni-plugin-v1.4.1-flannel1-amd64.tar # 验证镜像是否导入成功 ctr -n k8s.io images ls | grep flannel注意：必须在集群所有节点（包括master和worker）上执行相同的导入操作，否则调度到未导入镜像的节点时仍会失败。
2.3 修改Flannel部署配置
原始的kube-flannel.yml需要做两处关键修改：
- 将image地址改为本地镜像名称：
image: flannel/flannel:v0.25.1 # 改为 image: docker.io/flannel/flannel:v0.25.1- 显式设置镜像拉取策略：
imagePullPolicy: IfNotPresent3. 解决方案二：Harbor私有仓库配置
长期来看，搭建私有镜像仓库是更专业的解决方案。以下是针对containerd运行时的Harbor配置指南：
3.1 基础环境准备
| 组件 | 版本要求 | 备注 |
|---|---|---|
| Harbor | v2.0+ | 建议使用最新稳定版 |
| Containerd | 1.6+ | 需支持CRI插件 |
| Kubernetes | 1.24+ | 已移除dockershim |
3.2 Containerd配置Harbor
- 为Harbor创建配置文件目录：
mkdir -p /etc/containerd/certs.d/<harbor-host>:<port>- 创建
hosts.toml配置文件：
server = "http://<harbor-host>:<port>" [host."<harbor-host>:<port>"] capabilities = ["pull", "resolve", "push"] skip_verify = true- 重启containerd服务：
systemctl restart containerd3.3 镜像推送至Harbor
- 给镜像打标签：
docker tag flannel/flannel:v0.25.1 <harbor-host>:<port>/library/flannel:v0.25.1- 登录并推送镜像：
docker login <harbor-host>:<port> docker push <harbor-host>:<port>/library/flannel:v0.25.13.4 修改Flannel配置使用Harbor
最终的kube-flannel.yml关键修改部分：
containers: - name: kube-flannel image: <harbor-host>:<port>/library/flannel:v0.25.1 imagePullPolicy: IfNotPresent4. 高级配置与优化建议
4.1 镜像同步策略
对于生产环境，建议设置自动同步规则：
- 使用Harbor的复制功能定期从DockerHub同步基础镜像
- 配置镜像缓存代理（如Aliyun镜像加速器）
4.2 网络性能调优
Flannel支持多种后端，根据网络环境选择最佳方案：
| 后端类型 | 适用场景 | 性能特点 |
|---|---|---|
| VXLAN | 云环境/跨主机 | 通用性好，有一定开销 |
| Host-GW | 同机房物理机 | 性能最佳，要求二层连通 |
| UDP | 测试环境 | 兼容性最好，性能最差 |
修改后端类型只需在kube-flannel.yml中添加：
net-conf.json: | { "Network": "10.244.0.0/16", "Backend": { "Type": "vxlan" } }4.3 安全加固措施
- 为Harbor启用HTTPS
- 配置containerd的镜像拉取密钥：
ctr i pull --user <username>:<password> <harbor-host>:<port>/library/flannel:v0.25.15. 常见问题排查指南
当配置完成后仍然遇到问题时，可按以下步骤排查：
- 检查Pod状态：
kubectl get pods -n kube-flannel -o wide- 查看详细事件：
kubectl describe pod <pod-name> -n kube-flannel- 检查容器运行时日志：
journalctl -u containerd -f- 手动测试镜像拉取：
crictl pull <image-url>- 验证网络连通性：
ping <harbor-host> telnet <harbor-host> <port>对于特定的http: server gave HTTP response to HTTPS client错误，需要在pull命令中添加--plain-http参数：
ctr images pull <harbor-host>:<port>/library/flannel:v0.25.1 --plain-http