1. 这个报错不是“网络没通”，而是K8s节点彻底失去了容器网络身份
你执行kubectl get nodes看到节点状态是NotReady，再查日志发现 kubelet 反复报错：failed to setup network for pod "xxx": failed to find plugin "bridge", 或者更直白的提示——cni0 interface not found、flannel.1 does not exist。这时候很多人第一反应是“网络插件没装好”“flannel没启动”，立刻去kubectl get pods -n kube-system查 flannel pod 状态，发现它明明是Running，于是陷入困惑：pod在跑，但节点上连ip link show cni0都找不到这个网桥，ip addr show flannel.1也返回空。这不是“网络不通”，这是节点在 K8s 集群里已经“失联”了——它不再具备运行 Pod 的基本网络资格。
这个现象背后，本质是CNI 插件与 kubelet 的协同机制被破坏，而不仅仅是某个服务挂了。K8s 的网络模型里，cni0（Bridge 模式下）或flannel.1（VXLAN 模式下）不是由 flannel daemonset 单独创建并维护的静态资源；它们是 kubelet 在启动每个 Pod 前，调用 CNI 配置文件指定的二进制插件（如bridge、flannel）动态生成的。当 kubelet 启动时，它会读取/etc/cni/net.d/下的配置（比如10-flannel.conflist），再根据该配置调用/opt/cni/bin/下对应的插件二进制文件。如果插件调用失败、配置路径错误、二进制缺失、权限不对，或者更隐蔽的——CNI 配置中指定的 backend（如 VXLAN）所依赖的内核模块未加载，那么 kubelet 就会在首次尝试为 pause 容器配置网络时卡住，并持续重试，最终将节点标记为NotReady。
我遇到过最典型的误判场景：某次集群升级后，运维同学只检查了 flannel pod 的状态和日志，看到Starting IPAM...和Wrote subnet file...就认为一切正常，却忽略了kubelet日志里反复出现的failed to load plugin "flannel"和no such file or directory。后来追查发现，新内核版本默认禁用了vxlan模块，而 flannel 的BackendType配置为vxlan，导致flannel插件在初始化时无法创建flannel.1设备，进而使整个 CNI 调用链路崩溃。这说明，节点网络就绪 ≠ flannel pod 就绪，它是一个涉及内核、二进制、配置、权限四层联动的脆弱链条。本文接下来要拆解的，就是这条链路上每一个可能断裂的环节，以及如何用最小成本、最高效率定位到真正的断点。
2. 诊断不是靠猜，而是按 kubelet 的调用顺序逐层验证
诊断这类问题，绝不能从kubectl get nodes开始倒推，而必须严格遵循 kubelet 实际执行网络配置的调用栈：配置文件 → 插件二进制 → 内核模块 → 网络设备。跳过任何一层直接修改，都可能掩盖真实问题，甚至引发新故障。下面是我总结出的、经过数十个生产环境验证的四步黄金排查法，每一步都有明确的命令、预期输出和失败含义。
2.1 第一步：确认 CNI 配置文件存在且语法合法
kubelet 默认从/etc/cni/net.d/目录读取配置。首先检查该目录是否存在且非空：
ls -la /etc/cni/net.d/ # 正常应看到类似：10-flannel.conflist 99-loopback.conf接着，必须验证配置文件本身是否可被 CNI 解析。很多问题源于 YAML/JSON 语法错误（比如多了一个逗号、缩进错位），但 kubelet 日志往往只报failed to load network config，不提示具体哪一行。此时要用jq工具做语法校验：
# 检查 10-flannel.conflist 是否为合法 JSON jq '.' /etc/cni/net.d/10-flannel.conflist > /dev/null 2>&1 && echo "JSON OK" || echo "JSON ERROR" # 如果报错，用以下命令定位问题行（假设文件是 JSON 格式） jq -n 'fromjson' < /etc/cni/net.d/10-flannel.conflist 2>&1 | head -5提示：
conflist文件是 JSON 格式，不是 YAML。即使你用 YAML 工具编辑过，保存时也必须确保是纯 JSON。常见陷阱是使用了注释//或#，这在 JSON 中是非法的，会导致整个配置加载失败。
最关键的，是确认配置中plugins数组的第一个插件是否指向正确的二进制。打开10-flannel.conflist，找到类似这一段：
{ "cniVersion": "0.3.1", "name": "cbr0", "plugins": [ { "type": "flannel", "delegate": { "hairpinMode": true, "isDefaultGateway": true } }, { "type": "portmap", "capabilities": {"portMappings": true}, "snat": true } ] }这里type: "flannel"表明 kubelet 会去/opt/cni/bin/目录下寻找名为flannel的可执行文件。如果配置写成了"type": "flannel-cni"，而实际二进制名是flannel，就会直接失败。
2.2 第二步：验证 CNI 插件二进制文件存在、可执行且版本匹配
进入/opt/cni/bin/目录，检查flannel（或你配置中指定的 type 名）是否存在：
ls -l /opt/cni/bin/flannel # 正常输出应类似：-rwxr-xr-x 1 root root 24567890 Jan 1 10:00 /opt/cni/bin/flannel注意三个关键点：
- 权限必须是
rwx：如果只有r-x，kubelet 以 root 用户运行时通常没问题，但某些加固环境会限制exec权限，需确保x位存在。 - 文件大小不能为 0：曾遇到因
curl下载中断导致二进制文件为空，ls -l显示大小为 0。 - 版本必须与集群兼容：flannel v0.21+ 要求 CNI spec 1.0.0，而旧版 kubelet（<v1.24）默认使用 0.3.1 spec。如果版本不匹配，插件会拒绝工作。验证方法是运行插件自身进行自检（需提供 dummy 配置）：
# 创建一个最小化测试配置 cat > /tmp/test-conf.json << 'EOF' { "cniVersion": "0.3.1", "name": "testnet", "type": "flannel", "delegate": { "isDefaultGateway": true } } EOF # 手动调用插件 ADD 操作（模拟 kubelet 行为） echo '{}' | /opt/cni/bin/flannel /tmp/test-conf.json # 如果成功，会输出类似：{"cniVersion":"0.3.1","interfaces":[{"name":"cni0"}]} # 如果失败，会直接打印错误，如 "failed to load kernel module vxlan"注意：此测试必须在目标 node 上执行，且需保证
/tmp/test-conf.json中的cniVersion与你的实际配置一致。这是最直接的“绕过 kubelet，直击插件”的验证方式。
2.3 第三步：检查 CNI 插件依赖的内核模块是否已加载
这是最容易被忽略、也最致命的一环。flannel 的vxlanbackend 依赖vxlan内核模块，host-gw依赖dummy模块，ipsec依赖xfrm_user。如果模块未加载，插件在初始化阶段就会失败，且错误信息非常隐晦。
检查模块状态：
# 检查 vxlan 模块（flannel 默认 backend） lsmod | grep vxlan # 如果无输出，说明未加载 # 尝试手动加载 sudo modprobe vxlan # 检查是否加载成功 lsmod | grep vxlan # 如果报错 "Module vxlan not found in directory /lib/modules/$(uname -r)"，说明内核未编译该模块，需更换内核或改用 host-gw同样，检查dummy模块（host-gw backend 所需）：
lsmod | grep dummy sudo modprobe dummy关键经验：在自动化部署脚本中，必须在启动 flannel daemonset 之前，先执行
modprobe vxlan和modprobe dummy。很多 Ansible Playbook 或 kubeadm 初始化脚本遗漏了这一步，导致集群在特定内核版本下必然失败。我们曾在一个基于 Ubuntu 22.04 + kernel 5.15 的环境中踩坑，该内核默认禁用vxlan，modprobe命令需加--force参数才能加载，而标准脚本没有处理。
2.4 第四步：确认网络设备是否由插件正确创建
如果前三步都通过，但cni0或flannel.1依然不存在，问题就出在插件的 runtime 行为上。此时需要查看 flannel pod 的日志，但不是看kubectl logs，而是看它在 node 上生成的本地日志：
# flannel 通常将日志写入 /var/log/flannel.log sudo tail -50 /var/log/flannel.log # 或者查看 systemd journal（如果以 service 方式运行） sudo journalctl -u flanneld -n 50 --no-pager重点搜索关键词：Created subnet、Wrote subnet file、Initialized backend、Failed to create。一个健康的 flannel 启动日志应该包含：
I0101 10:00:00.000000 12345 main.go:517] Wrote subnet file to /run/flannel/subnet.env I0101 10:00:00.000000 12345 main.go:521] Running backend. I0101 10:00:00.000000 12345 vxlan.go:123] VXLAN init: VNI=1, Port=8472, GBP=false I0101 10:00:00.000000 12345 vxlan.go:145] Created L3 network 10.244.0.0/16 via 10.244.0.0/16如果看到Failed to create VXLAN device: operation not supported，那基本可以确定是内核模块问题；如果看到Failed to write subnet file: permission denied，则是/run/flannel/目录权限问题。
最后，手动触发一次网络配置，观察 kubelet 日志：
# 在 node 上，找一个正在运行的 pause 容器（通常是 kube-proxy 或 coredns 的 pause 容器） sudo crictl ps | grep pause | head -1 # 假设 CONTAINER_ID 是 abc123 sudo crictl exec -it abc123 sh -c "ip a" # 如果能进去，说明网络已通；如果进不去，再看 kubelet 日志 sudo journalctl -u kubelet -n 100 --no-pager | grep -A 5 -B 5 "cni0\|flannel.1\|network"3. flannel 的三种 Backend 模式：选错等于埋雷
flannel 支持vxlan、host-gw、ipsec三种主要 backend，它们不是简单的配置开关，而是代表了完全不同的网络数据平面实现，对底层基础设施的要求天差地别。很多团队在部署时直接采用官方 YAML 的默认vxlan，却从未评估过自己集群的网络环境是否真正支持它，结果在上线后遭遇性能抖动或间歇性丢包，根源就在这里。
3.1 VXLAN 模式：功能最强，但对内核和网络要求最高
vxlan是 flannel 的默认 backend，它通过在原始 IP 包外再封装一层 UDP 包（目的端口默认 8472），实现跨主机的二层网络通信。其优势是穿透性强，能在任意三层可达的网络上工作，无需底层网络支持特殊协议。
但它有三个硬性依赖：
- 内核模块
vxlan必须加载且可用（前文已详述）； - UDP 端口 8472 必须在所有 node 之间双向开放。很多企业防火墙策略默认只放行 TCP，会静默丢弃 VXLAN 流量，导致节点间
flannel.1设备虽存在，但无法通信； - MTU 必须精确计算。原始 MTU（如 1500）减去 VXLAN 头部（50 字节）后，有效 MTU 应为 1450。如果底层网络（如云厂商 VPC）的 MTU 小于 1450，就会引发分片，严重降低性能。我们曾在一个 AWS EKS 迁移项目中发现，由于 VPC 的 MTU 是 1400，而 flannel 未配置
mtu: 1400，导致大量 TCP 重传。
验证 VXLAN 是否真正在工作：
# 在 node A 上，ping node B 的 flannel 网段 IP（非物理 IP） # 先查 node B 的 flannel 网段分配（从 etcd 或 flannel 日志） # 假设是 10.244.1.0/24，取一个地址如 10.244.1.2 ping -c 3 10.244.1.2 # 同时在 node A 上抓包，看是否有 VXLAN 流量 sudo tcpdump -i any port 8472 -n -c 10 # 正常应看到类似：IP 10.0.1.10.8472 > 10.0.1.11.8472: UDP, length 1233.2 Host-GW 模式：极致简单，但要求所有 node 二层互通
host-gw（Host Gateway）模式完全不封装，它只是在每个 node 的路由表中添加一条静态路由，指向目标 node 的物理 IP。例如，node A 要访问10.244.1.10，它就在自己的路由表里加一条10.244.1.0/24 via 10.0.1.11（10.0.1.11 是 node B 的物理 IP）。
它的优势是零封装开销，性能接近裸金属，且完全不依赖内核模块。但代价是：所有 node 必须位于同一个二层广播域内，即能直接通过 ARP 学习到彼此的 MAC 地址。这在物理机房或私有云中可行，但在公有云（AWS/Azure/GCP）或跨机房场景中，由于网络架构限制，几乎不可能满足。
启用 host-gw 的配置片段：
{ "name": "cbr0", "type": "flannel", "backend": { "type": "host-gw" } }实操心得：如果你的集群部署在单个物理交换机下，或使用了支持 BGP 的 CNI（如 Calico），host-gw 是最稳定、最易排错的选择。我们曾用它支撑过一个 200+ 节点的金融交易系统，连续运行 18 个月无网络相关故障。但切记，启用前必须用
arping验证二层连通性：sudo arping -c 3 -I eth0 10.0.1.11（10.0.1.11 是目标 node 物理 IP），如果收不到 reply，host-gw 必然失败。
3.3 IPSEC 模式：安全优先，但 CPU 开销巨大
ipsecbackend 在 VXLAN 封装的基础上，再增加一层 IPSEC 加密（ESP 协议）。它解决了 VXLAN 的明文传输问题，适合对数据合规性要求极高的场景（如医疗、政务）。
但它有两个显著缺点：
- CPU 消耗高：加解密操作由 CPU 完成，会显著增加 node 的负载，在高吞吐场景下可能成为瓶颈；
- 配置复杂：需要预共享密钥（PSK）或证书体系，且密钥必须在所有 node 间同步，管理难度大。
启用 IPSEC 的配置：
{ "name": "cbr0", "type": "flannel", "backend": { "type": "ipsec", "psk": "your-secret-key-here" } }经验教训：除非有明确的等保三级或 GDPR 合规要求，否则不要轻易启用 IPSEC。我们曾为一个客户开启后，发现 node 的
sysCPU 使用率从 2% 暴涨至 35%，Pod 启动延迟从 200ms 增加到 2s。最终降级为 VXLAN + 网络 ACL 控制，既满足安全审计，又保障了性能。
4. 修复不是重启服务，而是重建 CNI 的信任链
当确认问题根源后，修复动作绝不是简单地systemctl restart kubelet或kubectl delete pod -n kube-system -l app=flannel。因为 kubelet 和 flannel 的状态是相互耦合的，盲目重启可能让问题更糟。正确的做法，是像重装一台机器一样，从底层开始，一层层重建 CNI 的信任链。
4.1 清理残留：删除所有 CNI 相关的网络设备和配置
在 node 上执行以下命令，彻底清除旧状态：
# 删除所有 cni 相关的网桥和接口 sudo ip link delete cni0 2>/dev/null sudo ip link delete flannel.1 2>/dev/null sudo ip link delete docker0 2>/dev/null # 如果同时运行 docker # 清空 CNI 配置目录 sudo rm -f /etc/cni/net.d/* # 清空 flannel 运行时数据 sudo rm -f /run/flannel/* sudo rm -f /var/run/flannel/* # 清空 kubelet 的网络缓存（关键！） sudo rm -f /var/lib/cni/*注意：
/var/lib/cni/是 kubelet 存储网络命名空间、IP 分配记录的地方。如果不清除，kubelet 可能会尝试复用一个已损坏的网络命名空间，导致后续配置永远失败。这是很多“重启无效”问题的终极原因。
4.2 重装插件：确保二进制、配置、模块三者同步
重新安装 CNI 插件二进制：
# 下载与你的 flannel 版本匹配的 CNI 插件包（例如 v1.1.2） curl -L "https://github.com/containernetworking/plugins/releases/download/v1.1.2/cni-plugins-linux-amd64-v1.1.2.tgz" | sudo tar -C /opt/cni/bin -xz # 确认 flannel 二进制也在 /opt/cni/bin/ 下（通常由 flannel daemonset 提供，但需确保版本一致） ls -l /opt/cni/bin/flannel重新生成 CNI 配置文件。不要直接复制旧文件，而是用 flannel 提供的mk-docker-opts.sh脚本生成（如果使用 docker）或手动编写：
# 以 VXLAN 为例，创建 /etc/cni/net.d/10-flannel.conflist sudo tee /etc/cni/net.d/10-flannel.conflist > /dev/null << 'EOF' { "cniVersion": "0.3.1", "name": "cbr0", "plugins": [ { "type": "flannel", "delegate": { "hairpinMode": true, "isDefaultGateway": true } }, { "type": "portmap", "capabilities": {"portMappings": true}, "snat": true } ] } EOF加载内核模块：
sudo modprobe vxlan # 为防止重启失效，写入配置 echo "vxlan" | sudo tee -a /etc/modules4.3 重启服务：按严格顺序，给每个组件充分的启动时间
顺序至关重要，必须遵守：
- 先启动 flannel daemonset：确保它有足够时间完成子网分配和设备创建；
- 等待 30 秒：让 flannel 写入
/run/flannel/subnet.env并创建flannel.1； - 再重启 kubelet：让它读取新的 CNI 配置并初始化网络。
手动执行：
# 1. 触发 flannel 重启（如果是 daemonset） kubectl rollout restart daemonset -n kube-system kube-flannel-ds # 2. 等待 flannel 就绪（检查 node 上的 flannel pod 和日志） kubectl get pods -n kube-system -l app=flannel # 等待其状态为 Running，且日志中出现 "Created L3 network" # 3. 30 秒后，重启 kubelet sudo systemctl restart kubelet # 4. 立即检查 kubelet 状态和日志 sudo systemctl status kubelet sudo journalctl -u kubelet -n 50 --no-pager | grep -i "cni\|network\|ready"关键技巧：在
systemctl restart kubelet后，不要立刻kubectl get nodes，而是先在 node 上执行sudo crictl ps，看是否有 pause 容器启动。如果有，再sudo crictl exec -it <pause-id> ip a，确认它是否获得了10.244.x.x的 IP。这是比kubectl get nodes更早、更底层的就绪信号。
4.4 验证闭环：从 Pod IP 到物理网络的全链路测试
修复完成后，必须进行四层验证，确保问题真正解决：
| 验证层级 | 命令 | 预期结果 | 意义 |
|---|---|---|---|
| 1. Node 本地网络 | ip link show cni0ip addr show flannel.1 | cni0网桥存在，flannel.1接口 UP | CNI 插件已成功创建基础设备 |
| 2. Pod 网络连通 | kubectl run test-pod --image=busybox:1.35 --rm -it --restart=Never -- ping -c 3 10.244.1.1 | 成功收到 reply | 跨 node 的 Pod 网络打通 |
| 3. Service 网络 | kubectl run test-svc --image=busybox:1.35 --rm -it --restart=Never -- nslookup kubernetes.default.svc.cluster.local | 返回 cluster IP（如 10.96.0.1） | kube-proxy 和 CoreDNS 工作正常 |
| 4. 外部访问 | kubectl run test-egress --image=busybox:1.35 --rm -it --restart=Never -- wget -qO- http://www.baidu.com | head -5 | 返回 HTML 片段 | SNAT 和外部网络出口正常 |
最后一个测试尤其重要。我们曾在一个修复后
kubectl get nodes显示Ready的集群中，发现所有 Pod 都无法访问外网。追查发现，portmap插件的snat: true配置被误删，导致出向流量没有做源地址转换。这提醒我们：Ready状态只代表 kubelet 认为网络“可用”，不代表它真的“可用”。
5. 预防胜于治疗：构建 CNI 就绪的自动化基线
在经历过多次因 CNI 故障导致的线上事故后，我们团队将 CNI 就绪检查固化为集群交付的强制基线。它不是一个“最好有”的建议，而是像“磁盘空间大于 20%”一样，是集群上线前必须通过的硬性门槛。
5.1 基线检查清单：五项不可妥协的准入条件
我们在每个新 node 加入集群前，都会运行一个名为cni-precheck.sh的脚本，它包含以下五个原子检查项，任何一项失败，node 就被拒绝加入：
内核模块检查：
# 必须加载 vxlan（或根据 backend 配置的模块） lsmod | grep -q vxlan || { echo "FAIL: vxlan module not loaded"; exit 1; }CNI 二进制完整性：
# 文件存在、非空、可执行 [ -x "/opt/cni/bin/flannel" ] && [ -s "/opt/cni/bin/flannel" ] || { echo "FAIL: flannel binary missing or empty"; exit 1; }CNI 配置合法性：
# 配置文件存在且 JSON 有效 [ -f "/etc/cni/net.d/10-flannel.conflist" ] || { echo "FAIL: CNI config missing"; exit 1; } jq -e '.' /etc/cni/net.d/10-flannel.conflist > /dev/null 2>&1 || { echo "FAIL: CNI config invalid JSON"; exit 1; }网络设备存在性：
# flannel.1 必须存在且 UP ip link show flannel.1 &>/dev/null || { echo "FAIL: flannel.1 interface not found"; exit 1; } ip link show flannel.1 | grep -q "state UP" || { echo "FAIL: flannel.1 is DOWN"; exit 1; }Pod 网络连通性：
# 在 node 上启动一个临时容器，ping 自己的 flannel 网段 IP # （利用 crictl，不依赖 kubectl） TEMP_POD=$(sudo crictl runp --runtime=runc /tmp/pause-config.json 2>/dev/null) sudo crictl exec -i $TEMP_POD sh -c "ping -c 1 10.244.0.1" &>/dev/null && echo "PASS" || { echo "FAIL: Pod network ping failed"; exit 1; } sudo crictl stopp $TEMP_POD &>/dev/null; sudo crictl rmp $TEMP_POD &>/dev/null
这个脚本被集成到我们的 Terraform 模块和 Ansible Playbook 中，确保每一台新购的物理服务器或云主机，在执行kubeadm join前，都已通过全部五项检查。
5.2 监控告警：把“cni0 不存在”变成一条可追踪的事件
在 Prometheus + Grafana 监控体系中，我们为 CNI 健康度定义了两个核心指标：
node_cni_interface_up{interface="cni0"}：Gauge 类型，值为 1 表示存在且 UP，0 表示不存在或 DOWN。采集方式是 node_exporter 的textfilecollector，配合一个每分钟执行的 shell 脚本：# /var/lib/node_exporter/textfile_collector/cni.prom echo "# HELP node_cni_interface_up Whether CNI interface is up" > /var/lib/node_exporter/textfile_collector/cni.prom echo "# TYPE node_cni_interface_up gauge" >> /var/lib/node_exporter/textfile_collector/cni.prom if ip link show cni0 &>/dev/null; then echo "node_cni_interface_up{interface=\"cni0\"} 1" >> /var/lib/node_exporter/textfile_collector/cni.prom else echo "node_cni_interface_up{interface=\"cni0\"} 0" >> /var/lib/node_exporter/textfile_collector/cni.prom fikube_node_status_phase{phase="NotReady"}：直接来自 kube-state-metrics，但增加了 label 过滤，只关注NotReady且持续时间超过 2 分钟的节点。
告警规则（Prometheus Alerting Rules）：
- alert: CNIInterfaceDown expr: node_cni_interface_up{interface="cni0"} == 0 for: 1m labels: severity: critical annotations: summary: "CNI interface cni0 is down on {{ $labels.instance }}" description: "The cni0 bridge interface is missing. This will cause all new Pods to fail network setup." - alert: NodeNotReadyForLong expr: kube_node_status_phase{phase="NotReady"} == 1 and on(instance) (kube_node_status_condition{condition="NetworkReady",status="true"} == 0) for: 2m labels: severity: warning annotations: summary: "Node {{ $labels.node }} is NotReady and NetworkReady is false" description: "This indicates a CNI failure. Check cni0 interface and flannel logs."实战效果：这套监控上线后，平均故障发现时间（MTTD）从 15 分钟缩短到 90 秒，且 90% 的告警都能准确定位到
cni0或flannel.1缺失，极大减少了人工排查的盲区。
5.3 文档沉淀：把每一次排错变成团队的知识资产
我们要求每一位 SRE 在解决完一个 CNI 相关故障后，必须提交一份cni-postmortem.md到内部知识库。这份文档不是流水账，而是结构化的问题复盘，包含四个固定章节：
- Root Cause：用一句话精准描述根本原因，例如：“内核 5.15.0-xx-generic 默认禁用 vxlan 模块，flannel 初始化失败”。
- Detection Path：详细记录从发现问题到定位根因的每一步命令和输出，包括哪些命令是无效的（避免后来者重复踩坑）。
- Fix Procedure：精确到每一行命令，注明执行顺序、依赖关系和预期耗时。
- Prevention Action：明确写出要加入基线检查、监控告警或自动化脚本的具体内容。
这些文档被自动索引，当新同事在 Slack 中输入/cni help vxlan时，机器人会推送最匹配的 3 篇 postmortem。久而久之，团队对 CNI 的理解就不再是零散的经验，而是一套可检索、可复用、可传承的知识图谱。
我在实际运维中发现，最危险的不是问题本身，而是问题被快速“修复”后留下的知识空白。一次成功的systemctl restart flanneld可能掩盖了内核模块缺失的真相，直到下一次内核升级才爆发。而一份扎实的 postmortem，能让整个团队在问题发生前，就把它扼杀在摇篮里。
