在 Debian 12 上使用 kubeadm 安装 Kubernetes 单主集群

一 环境准备

• 节点规划：至少 1 台控制平面（Master）+ 1 台工作节点（Worker），建议 2 核 CPU、2GB RAM、20GB 磁盘 起，生产环境适当提升规格。
• 系统要求：Debian 12（Bookworm），各节点间网络互通，主机名可解析，时间同步（建议启用 NTP）。
• 容器运行时：安装 containerd（推荐）或 Docker；下文以 containerd 为主，并给出 Docker 的备选方案。
• 安全与内核：关闭 Swap，开启桥接与转发内核参数。
• 防火墙：放通 6443（API Server）、10250（kubelet）、10251/10252（kube-scheduler/controller-manager）、以及 8472（Flannel VXLAN） 等端口（按实际网络插件与策略调整）。

二 安装与初始化步骤

• 1）系统更新与基础工具
  sudo apt update && sudo apt upgrade -y
  sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

• 2）安装并启用容器运行时（推荐 containerd）
  sudo apt install -y containerd
  sudo mkdir -p /etc/containerd
  containerd config default | sudo tee /etc/containerd/config.toml

  如使用 systemd cgroup，确保配置中 SystemdCgroup = true

  sudo systemctl daemon-reload
  sudo systemctl enable --now containerd

• 3）安装 kubeadm、kubelet、kubectl
  curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/kubernetes-archive-keyring.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 update
  sudo apt install -y kubelet kubeadm kubectl
  sudo apt-mark hold kubelet kubeadm kubectl

• 4）内核与系统参数（所有节点）
  sudo modprobe overlay
  sudo modprobe br_netfilter
  cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
  overlay
  br_netfilter
  EOF
  cat <<EOF | sudo tee /etc/sysctl.d/99-kubernetes.conf
  net.bridge.bridge-nf-call-iptables = 1
  net.ipv4.ip_forward = 1
  net.bridge.bridge-nf-call-ip6tables = 1
  EOF
  sudo sysctl --system

• 5）关闭 Swap（所有节点）
  sudo swapoff -a

  永久关闭：编辑 /etc/fstab，注释含 swap 的行

• 6）初始化控制平面（仅在 Master）

  使用 Flannel 时指定 Pod CIDR：10.244.0.0/16

  sudo kubeadm init --pod-network-cidr=10.244.0.0/16
  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

• 7）安装网络插件（Flannel，Master）
  kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

• 8）加入工作节点（在每个 Worker 执行）

  使用 kubeadm init 输出中的完整命令，形如：

  sudo kubeadm join :6443 --token --discovery-token-ca-cert-hash sha256:

• 9）验证
  kubectl get nodes
  kubectl cluster-info
  kubectl get pods -n kube-system

三 常见问题与排查

• 节点 NotReady：检查 kubelet 状态（sudo systemctl status kubelet）、容器运行时（sudo systemctl status containerd）、以及 Pod CIDR 是否与 Flannel 一致（10.244.0.0/16）。
• crictl 无法连接容器运行时：确认 containerd 正在运行且配置正确（/etc/containerd/config.toml 的 SystemdCgroup 与 sandbox_image）。
• 镜像拉取慢或失败：配置国内镜像源或使用私有镜像仓库，提前导入所需镜像。
• 时间不同步：启用 NTP/chrony，时间漂移会导致证书校验与组件异常。
• 端口被防火墙拦截：按需放通 6443、10250、8472 等端口，或临时关闭防火墙进行验证。

四 可选方案与提示

• 使用 Docker 作为运行时（备选）：安装 docker-ce 后，可通过 cri-dockerd 适配；或直接使用 containerd 简化维护。
• 其他网络插件：除 Flannel 外，也可选择 Calico 等，注意与 Pod CIDR 的一致性。
• 国内加速：配置 APT 镜像源 与 容器镜像加速器，显著提升下载速度。
• 生产建议：至少 2 个控制平面节点 实现高可用，并配置合适的 RBAC、网络策略、日志与监控。