在 Debian 12 上高效部署 Kubernetes 的实操指南
一 环境准备与规划
- 节点与网络
- 建议至少准备1 台控制平面 + 1 台工作节点，各节点具备静态 IP、主机名唯一、互通可达，并开启 NTP/chrony 时间同步。
- 硬件建议：控制平面至少2 核 CPU / 4 GB RAM / 20 GB 磁盘，工作节点至少2 核 CPU / 2 GB RAM / 20 GB 磁盘（生产环境建议更高规格）。
- 软件与权限
- 操作系统：Debian 12（Bookworm）；具备 sudo 权限的账户。
- 容器运行时：使用 containerd（Kubernetes 推荐，稳定且维护成本低）。
- 规划要点
- Pod 网段：如使用 Flannel，规划为 10.244.0.0/16；如使用 Calico，可按官方默认或按需规划。
- 控制平面端点：建议通过 负载均衡 VIP/DNS 对外暴露 6443，便于高可用与滚动升级。
二 一键化标准流程（kubeadm + containerd）
- 所有节点执行：系统更新、关闭 Swap、加载内核模块、设置 sysctl、安装并配置 containerd、安装 kubeadm/kubelet/kubectl
- 系统更新与基础工具
- sudo apt update && sudo apt upgrade -y
- sudo apt install -y apt-transport-https ca-certificates curl
- 关闭 Swap（重启后持久化）
- sudo swapoff -a
- sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab
- 加载内核模块与网络转发
- echo -e “overlay\nbr_netfilter” | sudo tee /etc/modules-load.d/k8s.conf
- sudo modprobe overlay && sudo modprobe br_netfilter
- echo -e “net.bridge.bridge-nf-call-iptables = 1\nnet.ipv4.ip_forward = 1” | sudo tee /etc/sysctl.d/99-kubernetes.conf
- sudo sysctl --system
- 安装并配置 containerd（使用 systemd cgroup）
- sudo apt install -y containerd
- 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 && sudo systemctl enable containerd
- 安装 kubeadm/kubelet/kubectl（版本保持一致）
- curl -fsSLo /usr/share/keyrings/kubernetes-archive-keyring.gpg https://packages.cloud.google.com/apt/doc/apt-key.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
- 控制平面节点初始化（示例）
- 使用 Flannel 时指定 Pod CIDR：sudo kubeadm init --pod-network-cidr=10.244.0.0/16
- 初始化完成后配置 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
- Calico：kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
- 工作节点加入
- 使用 kubeadm init 输出中的 kubeadm join 命令加入集群（包含 –token 与 –discovery-token-ca-cert-hash 参数）。
三 防火墙与端口放行（UFW 示例）
- 控制平面节点放行
- 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 10255/tcp # kubelet read-only (可选)
- sudo ufw reload
- 工作节点放行
- sudo ufw allow 10250/tcp # kubelet API
- sudo ufw allow 30000:32767/tcp # NodePort 范围（按需）
四 验证与常见问题处理
- 基础验证
- kubectl cluster-info
- kubectl get nodes
- kubectl get pods -A
- 常见问题速查
- 节点 NotReady：检查 containerd 是否运行、内核模块与 sysctl 是否生效、Pod 网段是否与网络插件一致（如 Flannel 使用 10.244.0.0/16）。
- kubelet 启动失败：确认已关闭 Swap、cgroup 驱动为 systemd、镜像拉取无阻塞（必要时配置国内镜像源/私有仓库）。
- 加入节点失败：确认 token 未过期、CA 哈希正确、控制平面 6443 与所需端口已放行、时间同步正常。
五 自动化与规模化部署建议
- 自动化工具
- KubeKey：支持一键拉起集群（示例：./kk create cluster --with-local-storage --with-kubernetes v1.31.0 --container-manager containerd -y）。
- Ansible：编写 Playbook 批量化执行系统准备、containerd 配置、kubeadm 初始化/加入等流程，便于复用与审计。
- 规模化与高可用
- 控制平面前置 负载均衡（VIP/DNS:6443），多控制平面 + etcd 集群部署，结合 kubeadm init/join 的 HA 流程与证书管理。