在 Debian 12 上使用 kubeadm 快速部署单主集群
一 环境准备
- 节点与网络
- 至少准备 1 台主节点 + 1 台工作节点，各节点建议 2 核 CPU / 2GB 内存 / 20GB 磁盘 起，保证节点间 IP 互通、时间同步（可用 NTP）。
- 建议为各节点设置 唯一主机名，并在所有节点的 /etc/hosts 中添加解析，便于维护。
- 系统与安全
- 更新系统：sudo apt update && sudo apt upgrade -y
- 关闭 Swap：sudo swapoff -a 并注释 /etc/fstab 中的 swap 行，避免 kubelet 异常。
- 防火墙（如启用 UFW）放行端口：控制面 6443/tcp，etcd 2379-2380/tcp，kubelet 10250/tcp，调度/控制 10251-10252/tcp，节点指标 10255/tcp；工作节点额外放行 NodePort 30000-32767/tcp。
二 安装容器运行时与网络基础
- 安装并启用 containerd（推荐，Kubernetes 官方推荐运行时）
- 安装组件：sudo apt install -y containerd
- 生成默认配置并启用 CRI：sudo mkdir -p /etc/containerd && sudo containerd config default | sudo tee /etc/containerd/config.toml
- 启动服务：sudo systemctl enable --now containerd
- 加载内核模块与开启转发（所有节点）
- 模块：sudo modprobe overlay && sudo modprobe br_netfilter
- sysctl：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
- 可选：安装 Docker（如更熟悉 Docker 生态）
- 安装：sudo apt install -y docker-ce docker-ce-cli containerd.io
- 启动：sudo systemctl enable --now docker。
三 安装 kubeadm kubelet kubectl
- 添加 Kubernetes APT 源并安装工具
- 导入密钥：curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
- 添加源：echo “deb 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
- 说明
- 上述源为当前主流写法，适用于 Debian 12；如后续仓库调整，请以官方指引为准。
四 初始化主节点与配置 kubectl
- 初始化集群（单主示例）
- 使用 Flannel：sudo kubeadm init --pod-network-cidr=10.244.0.0/16
- 使用 Calico（可选）：sudo kubeadm init --pod-network-cidr=192.168.0.0/16 --service-cidr=10.96.0.0/12
- 配置 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（Operator 方式）：kubectl apply -f https://docs.projectcalico.org/manifests/tigera-operator.yaml && kubectl apply -f https://docs.projectcalico.org/manifests/custom-resources.yaml
- 获取加入命令（用于工作节点）
- 重新生成：kubeadm token create --print-join-command
- 或复用初始化输出中的 kubeadm join … --token --discovery-token-ca-cert-hash sha256:。
五 加入工作节点与验证
- 工作节点加入
- 在各工作节点执行上一步得到的 kubeadm join 命令，完成后回到主节点检查状态。
- 验证集群
- 节点状态：kubectl get nodes（状态应为 Ready）
- 集群信息：kubectl cluster-info
- 系统 Pod：kubectl get pods -A
- 常见问题排查
- 确认 Swap 已关闭、containerd/kubelet 运行正常、防火墙端口放行、节点时间同步、主机名唯一；必要时查看 kubelet 日志 与 containerd 日志 定位问题。