Debian 12 上使用 kubeadm 部署 Kubernetes 的完整实战指南

一 环境准备与系统要求

• 节点规划：至少准备1 台 Master与1 台 Worker；生产建议3 台以上提升容错。
• 硬件建议：每节点至少2 核 CPU、2GB RAM、20GB 磁盘（更推荐4GB+ RAM与 SSD）。
• 操作系统：Debian 12 Bookworm，内核建议5.x及以上。
• 网络要求：节点间互通，可访问外网拉取镜像；规划好Pod 网络 CIDR与Service CIDR，避免与现有网段冲突。
• 主机标识：设置唯一主机名与 /etc/hosts 映射；克隆虚拟机需确保MAC 地址与product_uuid唯一。

二 系统初始化与容器运行时

• 更新与基础工具
  • sudo apt update && sudo apt upgrade -y
  • sudo apt install -y apt-transport-https ca-certificates curl
• 关闭 Swap（Kubelet 要求）
  • sudo swapoff -a
  • sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab
• 内核网络参数（桥接与转发）
  • echo -e “net.bridge.bridge-nf-call-iptables=1\nnet.bridge.bridge-nf-call-ip6tables=1\nnet.ipv4.ip_forward=1” | sudo tee /etc/sysctl.d/99-kubernetes.conf
  • sudo sysctl --system
• 加载内核模块
  • sudo modprobe br_netfilter
  • echo “br_netfilter” | sudo tee -a /etc/modules-load.d/k8s.conf
• 容器运行时 containerd（推荐）
  • sudo apt install -y containerd
  • sudo systemctl enable --now containerd

  • 生成默认配置并启用 SystemdCgroup

    sudo mkdir -p /etc/containerd containerd config default | sudo tee /etc/containerd/config.toml sudo sed -i ‘s/SystemdCgroup = false/SystemdCgroup = true/g’ /etc/containerd/config.toml sudo systemctl restart containerd
• 可选 Docker（如已安装，请确保 containerd 可用）
  • sudo apt install -y docker-ce docker-ce-cli containerd.io
  • sudo systemctl enable --now docker

三 安装 kubeadm kubelet kubectl

• 添加 Kubernetes APT 仓库（Debian 12 仍可使用 xenial 仓库名）
  • 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
• 启动 kubelet
  • sudo systemctl enable --now kubelet

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

• 初始化 Master（示例为 Flannel，Pod CIDR 使用 10.244.0.0/16）
  • sudo kubeadm init --pod-network-cidr=10.244.0.0/16

  • 如有多网卡或需指定 API 地址：–apiserver-advertise-address=<MASTER_IP>

• 配置 kubectl
  • mkdir -p $HOME/.kube
  • sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  • sudo chown $(id -u):$(id -g) $HOME/.kube/config
• 安装网络插件（二选一，保持与 Pod CIDR 一致）
  • 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 get nodes
  • kubectl get pods -n kube-system
• 加入 Worker 节点（使用 kubeadm init 输出命令）
  • sudo kubeadm join <MASTER_IP>:6443 --token --discovery-token-ca-cert-hash sha256:
• 可选 国内镜像加速（拉取 gcr.io 镜像）
  • kubeadm init --image-repository registry.aliyuncs.com/google_containers …

五 常见问题排查与安全加固

• 节点 NotReady
  • 确认 containerd 运行正常（sudo systemctl status containerd）
  • 检查 Pod CIDR 与网络插件是否匹配（Flannel 默认 10.244.0.0/16）
  • 查看 kubelet 日志：journalctl -u kubelet -f
• 镜像拉取失败
  • 配置 containerd 镜像加速（registry mirrors），或使用 –image-repository 指定国内仓库
• 端口与防火墙
  • 放行 6443（API）、10250（kubelet）、2379-2380（etcd）、10251/10252（kube-scheduler/controller）、以及 8472/4789（Flannel VXLAN）等；云环境在安全组放行
• 克隆虚拟机导致冲突
  • 检查并修正 /sys/class/dmi/id/product_uuid 与网卡 MAC 唯一性
• 安全加固建议
  • 启用 RBAC、最小权限与命名空间隔离
  • 限制对敏感端口访问，开启审核日志与节点加固
  • 定期升级 Kubernetes 组件与补丁