Debian 环境下 Kubernetes 网络配置实操指南
一 前置条件与内核网络
- 关闭 Swap：执行 sudo swapoff -a，并在 /etc/fstab 中注释 swap 行，确保 kubelet 正常运行。
- 加载内核模块与开启转发：
- 模块：sudo modprobe overlay && sudo modprobe br_netfilter
- Sysctl：
- net.bridge.bridge-nf-call-iptables = 1
- net.bridge.bridge-nf-call-ip6tables = 1
- net.ipv4.ip_forward = 1
- 持久化：写入 /etc/modules-load.d/containerd.conf 与 /etc/sysctl.d/99-kubernetes-k8s.conf 后执行 sudo sysctl --system。
- 容器运行时（推荐 containerd）：
- 安装 containerd 并生成默认配置：containerd config default | tee /etc/containerd/config.toml
- 在配置中设置 SystemdCgroup = true，并确认 sandbox_image（如 registry.k8s.io/pause:3.10），随后重启 containerd。
- 主机名与解析：为每个节点设置唯一主机名，并在 /etc/hosts 中维护节点 IP 与主机名映射，便于集群内解析。
- 防火墙（如启用 ufw）：放行控制面与工作节点端口，例如 6443/tcp、2379-2380/tcp、10250/tcp、10251-10252/tcp、10255/tcp，以及 NodePort 范围 30000:32767/tcp。
二 初始化集群与 Pod 网段规划
- 配置 APT 源（Debian 12+/bookworm 推荐新仓库路径）：
- curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
- echo “deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /” | tee /etc/apt/sources.list.d/kubernetes.list
- apt update && apt install -y kubeadm kubelet kubectl
- 初始化控制平面（示例）：
- kubeadm init --apiserver-advertise-address=<MASTER_IP> --pod-network-cidr=10.244.0.0/16 --service-cidr=10.100.0.0/16
- 如使用 kubeadm 配置文件，可在其中显式设置 controlPlaneEndpoint、advertiseAddress、criSocket、以及镜像仓库与证书周期等参数。
- 配置 kubectl：
- mkdir -p $HOME/.kube && sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config && sudo chown $(id -u):$(id -g) $HOME/.kube/config
- 说明：–pod-network-cidr 必须与所选 CNI 插件一致（例如 Calico 常用 10.244.0.0/16，Flannel 默认 10.244.0.0/16）。
三 安装 CNI 网络插件
- Calico（推荐生产使用）：
- kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
- 如使用 IPIP/VXLAN，确保节点间二层/三层可达，并按需调整 Calico 的 IPPool 与 MTU。
- Flannel（上手简单）：
- 下载官方 kube-flannel.yml 并执行 kubectl apply -f kube-flannel.yml
- 注意 Flannel 默认使用 10.244.0.0/16，需与 kubeadm 的 --pod-network-cidr 保持一致。
- 验证：
- watch kubectl get pods -n kube-system
- kubectl get nodes 确认所有节点状态为 Ready。
四 验证与常见问题排查
- 连通性验证：
- 部署测试应用：kubectl create deployment nginx-app --image=nginx --replicas=2
- 暴露服务：kubectl expose deployment nginx-app --name=nginx-web-svc --type=NodePort --port=80 --target-port=80
- 访问测试：kubectl get svc nginx-web-svc 获取 NodePort，然后从集群外部或节点 IP:NodePort 访问；也可进入 Pod 内部互访测试。
- 常见问题：
- 节点 NotReady：检查 CNI Pod 是否 Running、节点是否都禁用了 Swap、内核转发与 bridge-nf-call-iptables 是否生效。
- Pod 间不通：确认 Pod CIDR 与 CNI 配置一致、跨节点网络策略未阻断、物理/云网络 ACL 允许 VXLAN/IPIP 或对应封装流量。
- Service 访问异常：核对 Service ClusterIP/NodePort/LoadBalancer 类型与 kube-proxy 工作模式（iptables/ipvs）。
五 可选网络方案与端口策略
- 外部访问与高可用：可在管理/代理节点使用 Nginx Stream 代理 6443/tcp 到真实控制平面，统一入口并便于扩展。
- 端口策略示例（ufw）：
- 控制面：6443/tcp、2379-2380/tcp、10250/tcp、10251-10252/tcp、10255/tcp
- 工作节点：10250/tcp、NodePort 范围 30000:32767/tcp
- 策略建议：仅开放必要端口，最小化暴露面；在云环境结合安全组/NACL 实施白名单。
