Debian如何实现Kubernetes集群化部署

在 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 角色后启动集群并验证。