如何在Debian上部署K8S网络插件

在 Debian 上部署 Kubernetes 网络插件的实操指南

一 前置检查

• 确保已成功初始化控制平面，并且节点处于 NotReady 状态（尚未安装 CNI 时的正常状态）。
• 所有节点已禁用 Swap：执行 swapoff -a 并注释 /etc/fstab 中的 swap 行。
• 已加载内核模块并设置转发：
  • 模块：overlay、br_netfilter
  • sysctl：net.bridge.bridge-nf-call-iptables=1、net.ipv4.ip_forward=1
• 已安装并可用 kubectl，且 KUBECONFIG 指向 /etc/kubernetes/admin.conf。
• 如启用防火墙（UFW/iptables/firewalld），需放行控制面与节点通信端口（见文末端口清单）。

二 选择并部署网络插件

• 插件与 Pod CIDR 对照（需在 kubeadm init 时或清单中保持一致）：

  • Flannel：默认 10.244.0.0/16
  • Calico：常用 192.168.0.0/16（也可自定义，但不得与宿主机/Service CIDR 冲突）

• 部署 Flannel

  • 快速部署（默认网段 10.244.0.0/16）：

    kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
    

  • 如初始化时指定了其他 pod-network-cidr，请先下载清单并修改 net-conf.json 中的 Network 字段后再 apply。

• 部署 Calico

  • 快速部署（默认网段 192.168.0.0/16）：

    kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
    

  • 如需自定义 Pod CIDR（例如使用 10.244.0.0/16），下载清单，编辑 calico-config ConfigMap 中的 CALICO_IPV4POOL_CIDR 值，然后 apply。
  • 若节点使用 NetworkManager，为避免干扰 Calico 接口，创建文件 /etc/NetworkManager/conf.d/calico.conf：

    [keyfile]
    unmanaged-devices=interface-name:cali*;interface-name:tunl*;interface-name:vxlan.calico
    

  • 注意：Calico 为集群中唯一的网络提供商，不可与其他 CNI 并存。

三 验证与常见问题

• 验证插件与节点状态

  kubectl get nodes          # 状态应为 Ready
  kubectl get pods -n kube-system -w
  kubectl get pods --all-namespaces
  

• 快速连通性测试

  kubectl create deployment nginx-test --image=nginx:1.25 --replicas=2
  kubectl expose deployment nginx-test --port=80 --type=NodePort
  kubectl get svc nginx-test
  # 从集群外访问 NodeIP:NodePort
  

• 常见问题与处理
  • 节点长时间 NotReady：检查 CNI 是否成功部署、Pod CIDR 是否匹配、/etc/cni/net.d 是否生成配置、以及 kubelet 日志。
  • 镜像拉取失败：国内环境可使用镜像加速或替换为国内镜像源后重试。
  • 使用 Weave/其他插件遇到互通问题：可能与 iptables/nftables 兼容有关，可执行：

    sudo update-alternatives --config iptables
    # 选择 iptables-legacy 以规避兼容性问题
    

  • 重置与重试（谨慎操作，会清理集群）：

    sudo kubeadm reset
    sudo rm -rf /etc/cni/net.d
    sudo iptables -F && sudo iptables -t nat -F && sudo iptables -t mangle -F && sudo iptables -X
    # 重新 init 后再部署 CNI
    

四 防火墙与端口放行清单

• 控制平面节点（示例 UFW）

  sudo ufw allow 6443/tcp     # API Server
  sudo ufw allow 2379:2380/tcp # etcd
  sudo ufw allow 10250/tcp   # kubelet API
  sudo ufw allow 10251/tcp   # kube-scheduler
  sudo ufw allow 10252/tcp   # kube-controller-manager
  sudo ufw reload
  

• 工作节点

  sudo ufw allow 10250/tcp   # kubelet API
  sudo ufw allow 30000:32767/tcp # NodePort 范围
  sudo ufw reload
  

• 如使用 Calico 的 IPIP/VXLAN 或 Flannel VXLAN，还需放行相关封装与 BGP 端口（如 4789/udp 等），具体以所用插件文档为准。