在 Debian 12 上使用 kubeadm 部署多节点 Kubernetes 集群
一 环境与规划
- 准备至少 3 台机器（建议 1 台控制平面 + 2 台工作节点），示例规划：
- 控制平面：k8s-master01（192.168.16.20）
- 工作节点：k8s-node01（192.168.16.21）、k8s-node02（192.168.16.22）
- 硬件建议：每节点至少 2 核 CPU / 2 GB RAM / 20 GB 磁盘
- 操作系统：Debian 12
- 网络要求：节点间 互通，时间 同步，并 禁用 Swap
- 容器运行时：使用 containerd（Kubernetes 自 v1.20 起推荐）
二 所有节点通用准备
- 设置主机名与 hosts
- 设置主机名：sudo hostnamectl set-hostname k8s-master01（各节点分别设置）
- 统一 hosts：在所有节点编辑 /etc/hosts
- 192.168.16.20 k8s-master01.test.local k8s-master01
- 192.168.16.21 k8s-worker01.test.local k8s-worker01
- 192.168.16.22 k8s-worker02.test.local k8s-worker02
- 禁用 Swap
- sudo swapoff -a
- sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab
- 内核与模块（桥接流量与转发）
- cat <<EOF | sudo tee /etc/modules-load.d/containerd.conf
overlay
br_netfilter
EOF
- 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.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-ip6tables = 1
EOF
- sudo sysctl --system
- 安装并配置 containerd
- sudo apt update && sudo apt install -y containerd
- sudo mkdir -p /etc/containerd
- containerd config default | sudo tee /etc/containerd/config.toml
- 在 [plugins.“io.containerd.grpc.v1.cri”.containerd.runtimes.runc.options] 下确保 SystemdCgroup = true
- sudo systemctl enable --now containerd
- 安装 kubeadm、kubelet、kubectl
- sudo apt update
- sudo apt install -y apt-transport-https ca-certificates curl gpg
- 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
- sudo systemctl enable --now kubelet
- 防火墙放行（如使用 UFW）
- 控制平面：sudo ufw allow 6443/tcp,2379/tcp,2380/tcp,10250/tcp,10251/tcp,10252/tcp,10255/tcp
- 工作节点：sudo ufw allow 10250/tcp,30000:32767/tcp
- 如部署 Calico，额外放行：179/tcp,4789/udp（必要时 51820/udp,51821/udp）
- 统一执行：sudo ufw reload
三 初始化控制平面
- 初始化命令（按需替换 API 地址 与 Pod 网段）
- 使用固定 Pod CIDR（Flannel 常用）：sudo kubeadm init --apiserver-advertise-address=192.168.16.20 --pod-network-cidr=10.244.0.0/16
- 或使用 kubeadm 默认网段：sudo kubeadm init --apiserver-advertise-address=192.168.16.20
- 配置 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
- 验证控制平面
- kubectl get nodes
- kubectl cluster-info
四 加入工作节点
- 获取加入命令
- 在控制平面查看：kubeadm token create --print-join-command
- 在各工作节点执行（替换为实际输出）
- sudo kubeadm join 192.168.16.20:6443 --token --discovery-token-ca-cert-hash sha256:
- 验证
- 控制平面执行：kubectl get nodes（状态应为 Ready）
五 常见问题与扩展
- 镜像拉取问题（国内环境）
- 预先用国内镜像仓库拉取所需镜像并重新打 tag，或使用镜像加速与私有仓库；kubeadm 初始化前可用 kubeadm config images list 查看所需镜像清单
- 重置与重新加入
- 重置节点：sudo kubeadm reset；必要时清理 /etc/cni/net.d 并重置 iptables
- 重新生成 join 命令：kubeadm token create --print-join-command
- 高可用控制平面
- 生产环境建议使用 多 Master + etcd 集群；可基于 kubeadm 或采用自动化工具（如 kubeasz）进行多主高可用部署与扩容
