Linux kubeadm init 的 –pod-network-cidr 与 CNI 插件兼容性检查

–pod-network-cidr 必须与所选 cni 插件（calico/flannel/cilium）配置的网段严格一致，否则 kubelet 启动失败或 pod 无法调度；calico 最严格，需匹配 ippool；flannel 依赖 net-conf.json；cilium 虽不直接使用该参数，但影响 node podcidrs 分配。

pod-network-cidr 不匹配 CNI 插件会导致 kubelet 启动失败

绝大多数 CNI 插件（如 Calico、Flannel、Cilium）要求 --pod-network-cidr 和其自身配置的网段完全一致，否则 kubelet 会拒绝启动 Pod，日志里反复出现 Failed to set up sandbox container 或 networkPlugin cni failed to set up pod。这不是“稍后能自动修复”的问题，而是初始化阶段就卡死。

实操建议：

• 运行 kubeadm init 前，先查清你准备用的 CNI 插件默认期望的网段（比如 Flannel 默认是 10.244.0.0/16，Calico 默认是 192.168.0.0/16）
• 务必让 --pod-network-cidr 和 CNI 配置中 podCIDR 或 ipam.subnet 字段严格一致——注意斜杠位数和起始地址都不能差
• 别依赖文档里的“推荐值”，直接看插件 YAML 文件里 net-conf.json 或 ConfigMap 的实际内容

Calico 要求 –pod-network-cidr 必须与 calicoctl get ippool 输出一致

Calico 对网段一致性检查最严格：它不仅比对初始配置，还会在运行时校验集群中已存在的 IPPool 资源。如果 --pod-network-cidr=192.168.0.0/16，但 calicoctl get ippool -o wide 显示的是 192.168.128.0/17，节点加入后立即无法分配 IP。

实操建议：

• 初始化前执行 curl https://docs.projectcalico.org/manifests/calico.yaml -O，然后 grep 192.168.0.0/16 确认默认值
• 如果要改网段，必须同步修改 YAML 中两处：CALICO_IPV4POOL_CIDR 环境变量 + spec.cidr 字段（后者在 kind: IPPool 下）
• 不要只改 kubeadm init 参数而漏掉 YAML，否则 Control Plane 初始化成功，Worker 节点 join 后直接卡在 NotReady

Flannel 的 –pod-network-cidr 必须和 kube-flannel.yml 里 net-conf.json 完全对应

Flannel 不校验集群状态，但它把网段硬编码在 ConfigMap 的 net-conf.json 里。如果你用 --pod-network-cidr=10.244.0.0/16 初始化，却部署了未修改的官方 kube-flannel.yml（里面 "Network": "10.244.0.0/16"），看似没问题；但一旦你手误写成 10.245.0.0/16，所有 Pod 的 status.phase 会长期卡在 Pending，kubectl describe pod 显示 Failed create pod sandbox。

实操建议：

• 下载 kube-flannel.yml 后，立刻搜索 Network，确保 JSON 值和 --pod-network-cidr 一模一样
• Flannel 不支持多网段，也**不支持** CIDR 变长掩码（例如 /24），最小有效单位是 /16，否则 flanneld 进程启动即退出，报错 invalid network CIDR
• 别用 sed -i 替换整个文件，容易误改注释或其它字段；定位到 net-conf.json section 再改

Cilium 的 –pod-network-cidr 仅用于 kube-controller-manager 分配 Node CIDR，和 CNI 实际行为无关

Cilium 是个例外：它不读取 --pod-network-cidr 做网络配置，而是通过 ClusterMesh 或 ENI 模式动态管理地址空间。但 kube-controller-manager 仍会用这个参数给每个 Node 分配 spec.podCIDRs，如果填错，会导致 Node 资源里 podCIDRs 字段为空，进而让 Cilium operator 无法生成正确的 Node CRD，最终所有 Pod 失去网络策略控制。

实操建议：

• 即使用 Cilium，--pod-network-cidr 也要设——通常填 10.0.0.0/8 或 10.244.0.0/16（和 Cilium Helm chart 默认 ipam.mode=cluster-pool 的范围对齐）
• 部署 Cilium 后，立刻检查 kubectl get node -o wide 输出中 PODCIDR 列是否非空；为空说明 --pod-network-cidr 未生效或被覆盖
• Cilium 自带校验命令：cilium status --verbose | grep -A3 "Cluster IPs"，确认输出的 PodCIDR 和 kubectl get node <name> -o jsonpath='{.spec.podCIDRs}'</name> 一致

最容易被忽略的一点：kubeadm 不校验 --pod-network-cidr 是否与其他组件冲突，也不会提示你该值是否已被占用。它只负责写进 kubeadm-config ConfigMap 和 kube-controller-manager 启动参数。真正出问题，往往在 CNI 插件加载之后——那时 kubelet 日志已经刷屏，排查路径变长。