在 Debian 12 上使用 kubeadm 搭建 Kubernetes 集群
一 环境准备
- 节点与硬件：至少准备2 台服务器（1 个 Master、1 个或多个 Worker），每台建议至少2 核 CPU、2 GB 内存、20 GB 磁盘，并确保节点间网络互通。如使用云服务器，请确认安全组/防火墙已放通相关端口。时间同步建议启用 NTP。
- 系统设置：所有节点执行以下基础配置
- 关闭 Swap：
sudo swapoff -a
sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab
- 加载内核模块与开启桥接转发：
echo -e “overlay\nbr_netfilter” | sudo tee /etc/modules-load.d/containerd.conf
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
EOF
sudo sysctl --system
- 可选：设置主机名与 /etc/hosts，便于管理（如 master、worker1、worker2）。
二 安装容器运行时与 Kubernetes 组件
- 安装 containerd（推荐）：
sudo apt update && sudo apt install -y apt-transport-https ca-certificates curl gpg
sudo apt install -y containerd.io
sudo systemctl enable --now containerd
- 安装 kubeadm、kubelet、kubectl（所有节点）：
curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor | sudo tee /usr/share/keyrings/kubernetes-apt-keyring.gpg >/dev/null
echo “deb [signed-by=/usr/share/keyrings/kubernetes-apt-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
说明：上述使用 containerd 作为运行时；若你更熟悉 Docker，也可安装 Docker 并将 containerd 作为其内置运行时使用（生产环境更推荐直接使用 containerd）。
三 初始化控制平面并配置 kubectl
- 初始化 Master（仅在 Master 节点执行）：
sudo kubeadm init --pod-network-cidr=10.244.0.0/16
提示：如有多网卡或需要指定 API 地址，可追加如 –apiserver-advertise-address=。初始化成功后，控制台会输出 kubeadm join 命令，请妥善保存。
- 配置 kubectl（仅在 Master 节点执行）：
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
完成后可执行 kubectl 命令验证控制平面组件是否就绪。
四 安装网络插件与加入工作节点
- 安装 Pod 网络插件（二选一，保持与 --pod-network-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
- 加入 Worker 节点（在每个 Worker 节点执行 Master 输出的命令）：
sudo kubeadm join :6443 --token --discovery-token-ca-cert-hash sha256:
- 验证集群状态（在 Master 节点执行）：
kubectl get nodes
kubectl get pods -A
当所有节点状态为 Ready 且核心系统 Pod 均为 Running，集群即搭建完成。
五 防火墙与常见问题处理
- 防火墙放通端口（示例为 UFW，如使用 firewalld/云安全组请对应放通）：
sudo ufw allow 6443/tcp # API Server
sudo ufw allow 2379:2380/tcp # etcd
sudo ufw allow 10250/tcp # kubelet API
sudo ufw allow 10251/tcp # kube-scheduler
sudo ufw allow 10252/tcp # kube-controller-manager
sudo ufw allow 30000:32767/tcp # NodePort 范围
- 常见问题速查：
- 节点 NotReady：多因网络插件未就绪或 Pod CIDR 不匹配，检查 kube-flannel.yml/calico.yaml 的 CIDR 与 kubeadm init 参数是否一致。
- kubeadm join 失败：确认 token 未过期（默认 24 小时），必要时在 Master 执行 kubeadm token create --print-join-command 重新生成；确保 6443 与 10250 等端口可达。
- 镜像拉取慢/失败：可配置国内镜像源或使用 kubeadm 的镜像仓库镜像参数（imageRepository）。