Kubernetes在Debian上的部署教程

在 Debian 12 上使用 kubeadm 部署单主集群

本教程基于 Debian 12，使用 kubeadm 快速搭建一个单主（1 控制平面 + N 工作节点）Kubernetes 集群，并部署 Flannel 网络插件，完成后可进行应用部署与日常运维。

一 环境准备与前置条件

• 节点规划：至少 1 台控制平面 + 1 台工作节点；推荐硬件为 2 核 CPU / 2GB RAM / 20GB 磁盘（生产环境建议更高规格）。
• 系统要求：建议使用 Debian 12 Bookworm，所有节点间网络互通，具备 sudo 权限与稳定互联网连接。
• 唯一性校验：确保各节点的 MAC 地址 与 product_uuid 唯一（克隆/虚拟化环境需重点检查）。
• 主机名与解析：为各节点设置清晰主机名，并在 /etc/hosts 中添加解析（便于内网直连与排查）。
• 防火墙与端口：开放 6443、10250、10251、10252、2379、2380、8472/udp（VXLAN） 等端口（或临时关闭防火墙用于测试）。
• 容器运行时：本教程以 Docker 为例（也可用 containerd，见文末说明）。

二 所有节点通用配置

• 更新系统与基础工具

  sudo apt update &
      &
       sudo apt upgrade -y
  sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
  

• 关闭 Swap（Kubernetes 要求）

  sudo swapoff -a
  sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab
  

• 内核模块与网络参数（启用桥接与转发）

  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
  

• 安装容器运行时（Docker）

  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 enable --now docker
  

• 安装 kubeadm、kubelet、kubectl

  curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
  echo "deb 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
  

以上步骤完成后，所有节点应已具备容器运行环境与 Kubernetes 基础组件，且完成必要的内核与网络调优。

三 初始化控制平面

• 初始化集群（单主示例）

  sudo kubeadm init --pod-network-cidr=10.244.0.0/16
  

  说明：
  • 如使用 Flannel，Pod 网段 10.244.0.0/16 是推荐值；如使用 Calico，常见为 192.168.0.0/16（需与 Calico 清单一致）。
  • 初始化成功后，终端会输出 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
  

• 验证控制平面

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

等待数分钟，控制平面与系统 Pod 就绪后，节点状态应变为 Ready。

四 加入工作节点

• 在工作节点执行初始化时输出的 kubeadm join 命令，例如：

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

• 如令牌过期，可在控制平面重新生成：

  kubeadm token create --print-join-command
  

• 回到控制平面验证：

  kubectl get nodes
  

所有加入节点就绪后，集群即具备基本的调度与网络能力。

五 常见问题与优化

• 镜像拉取缓慢或失败：可使用国内镜像仓库（如 registry.aliyuncs.com/google_containers）替换 kubeadm 默认仓库，或在 kubeadm 初始化时通过 –image-repository 指定；也可提前在各节点手动拉取所需镜像。
• 防火墙/安全组：确保节点间开放 6443、10250、10251、10252、2379、2380、8472/udp 等端口，或测试环境临时关闭防火墙。
• 容器运行时选择：除 Docker 外，也可使用 containerd（生产常用，资源开销更低）；若使用 containerd，需按官方指引完成配置与 CRI 启用。
• 节点 NotReady：优先检查 kubelet 服务状态、CNI 网络插件是否成功部署、以及 Pod CIDR 是否与网络插件配置一致。
• 克隆/虚拟化环境：确保 MAC 地址 与 product_uuid 唯一，避免 kubelet 误判为同一节点。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！