在 Debian 上部署 Kubernetes 集群的可执行方案
一 方案总览与准备
- 推荐在 Debian 11/12 上使用 kubeadm 搭建生产可用的 Kubernetes 集群，容器运行时优先选择 Containerd（与 kubelet 的 systemd cgroup 驱动配合更稳定）。基础要求：每节点至少 2 核 CPU、2 GB RAM、20 GB 磁盘，节点间网络互通，主机名唯一，时间同步（建议启用 NTP/chrony），并永久关闭 Swap。如使用防火墙，放行控制平面与工作节点所需端口（见下文）。硬件与系统基线、端口要求与基础检查可参考下述实践。
二 使用 kubeadm 的标准部署步骤
- 所有节点
- 更新与基础工具
- sudo apt-get update && sudo apt-get upgrade -y
- sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release
- 加载内核模块与开启转发（Containerd 前置）
- echo -e “overlay\nbr_netfilter” | sudo tee /etc/modules-load.d/containerd.conf
- sudo modprobe overlay && sudo modprobe br_netfilter
- cat <<EOF | sudo tee /etc/sysctl.d/99-kubernetes-k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF
- sudo sysctl --system
- 安装并配置 Containerd
- sudo apt-get install -y containerd
- containerd config default | sudo tee /etc/containerd/config.toml >/dev/null 2>&1
- sudo sed -i ‘s/SystemdCgroup = false/SystemdCgroup = true/’ /etc/containerd/config.toml
- sudo systemctl daemon-reload && sudo systemctl enable --now containerd
- 安装 kubelet/kubeadm/kubectl（版本保持一致）
- curl -fsSLo /usr/share/keyrings/kubernetes-archive-keyring.gpg https://packages.cloud.google.com/apt/doc/apt-key.gpg
- echo “deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main” | sudo tee /etc/apt/sources.list.d/kubernetes.list
- sudo apt-get update && sudo apt-get install -y kubelet kubeadm kubectl
- sudo apt-mark hold kubelet kubeadm kubectl
- sudo systemctl enable --now kubelet
- 关闭 Swap
- sudo swapoff -a
- sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab
- 控制平面节点
- 初始化集群（按需替换参数；Pod 网段与所选 CNI 保持一致）
- sudo kubeadm init
–apiserver-advertise-address=<MASTER_IP>
–pod-network-cidr=10.244.0.0/16
–control-plane-endpoint=<MASTER_IP>:6443
–service-cidr=10.96.0.0/12
- 配置 kubectl
- mkdir -p $HOME/.kube
- sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
- sudo chown $(id -u):$(id -g) $HOME/.kube/config
- 安装 CNI 网络插件（二选一）
- Flannel：kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
- Calico：kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
- 工作节点
- 使用 kubeadm init 输出或重新生成的 join 命令加入
- sudo kubeadm join <MASTER_IP>:6443 --token --discovery-token-ca-cert-hash sha256:
- 验证
- kubectl cluster-info
- kubectl get nodes
- kubectl get pods -A
- 常用运维
- 重新生成 join 命令：kubeadm token create --print-join-command
- 重置节点：kubeadm reset（清理 /etc/cni/net.d、iptables 等后重装）
三 防火墙与端口规划
- 控制平面节点放行：6443/TCP（API）、2379–2380/TCP（etcd）、10250/TCP（kubelet）、10251/TCP（kube-scheduler）、10252/TCP（kube-controller-manager），必要时 10255/TCP（kubelet 只读）。
- 工作节点放行：10250/TCP（kubelet）、30000–32767/TCP（NodePort 范围）。
- 如使用 UFW：ufw allow <端口>/tcp 并 reload；如使用 firewalld/云安全组，按上述端口放行。
四 高可用与控制平面端点
- 多控制平面部署建议：准备 3 台或 5 台控制平面节点，前置 负载均衡器（VIP/域名指向 API 端口 6443），在 init/join 时使用 –control-plane-endpoint=:6443；kubeadm 将部署 Keepalived + kube-vip 或云上 LB 的健康检查与虚 IP 漂移。
- 加入控制平面节点示例：
- sudo kubeadm join :6443 --token --discovery-token-ca-cert-hash --control-plane
- 工作节点 join 命令与控制平面一致（不带 --control-plane）。完成后使用 kubectl get nodes 与 kubectl get pods -n kube-system 校验各组件就绪。
五 常见问题与替代方案
- 常见问题
- 节点 NotReady：多因 CNI 未安装/网段不匹配、cgroup 驱动不一致（Containerd 需 SystemdCgroup=true）、或 Swap 未关闭；按上文核对并修正后重启 kubelet。
- join 命令过期：在主节点执行 kubeadm token create --print-join-command 获取新命令。
- 镜像拉取慢/失败：配置国内镜像加速或使用企业私有镜像仓库；必要时在 kubeadm 初始化时指定 –image-repository（如国内镜像源）。
- 替代方案
- RKE2（Rancher Kubernetes Engine）：在 Debian 11 上也可用 RKE2 快速部署高可用集群，适合需要内置 Rancher 集成、简化运维 的场景；安装 RKE2、配置 server/agent 角色后启动集群并验证。