探索Debian上Kubernetes的部署之道

在 Debian 12 上使用 kubeadm 部署 Kubernetes 的实操指南

一 环境与前置准备

• 节点规划：至少准备 1 台控制平面 与 1 台工作节点；推荐 2 核 CPU、2GB 内存、20GB 磁盘 起步，并保证节点间网络互通。
• 系统与网络：建议使用 Debian 12（Bookworm）；为各节点设置唯一 主机名 并在 /etc/hosts 中完成解析；所有节点 禁用 Swap（执行 sudo swapoff -a 并注释 fstab 中的 swap 行）。
• 容器运行时：选择 containerd（推荐）或 Docker CE；二者择一即可。
• 防火墙与端口：如使用 UFW，在主控节点放行 6443、2379、2380、10250、10251、10252、10255/tcp，在工作节点放行 10250/tcp 与 30000–32767/tcp（NodePort 范围）。

二 安装容器运行时

• 方案 A containerd（推荐）
  • 内核模块与 sysctl：

    sudo tee /etc/modules-load.d/containerd.conf <<EOF
    overlay
    br_netfilter
    EOF
    sudo modprobe overlay
    sudo modprobe br_netfilter
    
    sudo tee /etc/sysctl.d/99-kubernetes-k8s.conf <<EOF
    net.bridge.bridge-nf-call-iptables  = 1
    net.ipv4.ip_forward                 = 1
    EOF
    sudo sysctl --system
    

  • 安装与配置：

    sudo apt update
    sudo apt install -y containerd
    sudo mkdir -p /etc/containerd
    containerd config default | sudo tee /etc/containerd/config.toml
    sudo systemctl restart containerd
    sudo systemctl enable containerd
    

• 方案 B Docker CE

  sudo apt update
  sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
  curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
  echo "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list
  sudo apt update
  sudo apt install -y docker-ce docker-ce-cli containerd.io
  sudo systemctl start docker
  sudo systemctl enable docker
  

三 安装 kubeadm kubelet kubectl

• 添加 Kubernetes APT 仓库并安装组件（Debian 12 仍可使用 kubernetes-xenial 仓库条目）：

  sudo apt update
  sudo apt install -y apt-transport-https curl ca-certificates gnupg
  curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor | sudo tee /usr/share/keyrings/kubernetes-archive-keyring.gpg >/dev/null
  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 update
  sudo apt install -y kubelet kubeadm kubectl
  sudo apt-mark hold kubelet kubeadm kubectl
  

• 说明：上述仓库条目为社区常用写法，适用于 Debian 12；如后续仓库调整，请以官方发布为准。

四 初始化控制平面与网络插件

• 初始化（单控制平面示例，按需替换参数）：

  sudo kubeadm init \
    --pod-network-cidr=10.244.0.0/16 \
    --apiserver-advertise-address=<MASTER_IP> \
    --control-plane-endpoint=<MASTER_IP>:6443 \
    --service-cidr=10.100.0.0/16
  

  初始化成功后，按提示保存输出的 kubeadm join 命令，用于工作节点加入。
• 配置 kubectl：

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config
  

• 安装网络插件（二选一）
  • 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
    

• 验证：

  kubectl cluster-info
  kubectl get nodes
  kubectl get pods -n kube-system
  

五 加入工作节点与验证

• 工作节点加入（使用初始化时生成的命令，注意端口为 6443）：

  sudo kubeadm join <MASTER_IP>:6443 \
    --token <TOKEN> \
    --discovery-token-ca-cert-hash sha256:<HASH>
  

• 如 token 过期，可在控制平面生成新 token：

  kubeadm token create --print-join-command
  

• 再次验证：

  kubectl get nodes
  kubectl get pods --all-namespaces
  

• 常见问题排查要点
  • 所有节点 MAC 地址 与 product_uuid 需唯一（克隆虚拟机时易冲突）。
  • 确认 6443/10250 等端口已放行，且 /etc/hosts 解析正确。
  • 确认 Swap 已关闭、内核参数与模块加载正确、容器运行时处于 active 状态。