--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，然后 grep192.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.jsonsection 再改
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 日志已经刷屏，排查路径变长。
