Kubernetes在Debian上的部署教程

在 Debian 12 上使用 kubeadm 部署单主集群

本教程基于 Debian 12，使用 kubeadm 快速搭建一个单主（1 控制平面 + N 工作节点）Kubernetes 集群，并部署 Flannel 网络插件，完成后可进行应用部署与日常运维。

一环境准备与前置条件

节点规划：至少 1 台控制平面 + 1 台工作节点；推荐硬件为 2 核 CPU / 2GB RAM / 20GB 磁盘（生产环境建议更高规格）。
系统要求：建议使用 Debian 12 Bookworm，所有节点间网络互通，具备 sudo 权限与稳定互联网连接。
唯一性校验：确保各节点的 MAC 地址 与 product_uuid 唯一（克隆/虚拟化环境需重点检查）。
主机名与解析：为各节点设置清晰主机名，并在 /etc/hosts 中添加解析（便于内网直连与排查）。
防火墙与端口：开放 6443、10250、10251、10252、2379、2380、8472/udp（VXLAN） 等端口（或临时关闭防火墙用于测试）。
容器运行时：本教程以 Docker 为例（也可用 containerd，见文末说明）。

二所有节点通用配置

更新系统与基础工具

sudo apt update && sudo apt upgrade -y
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

关闭 Swap（Kubernetes 要求）

sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

内核模块与网络参数（启用桥接与转发）

sudo tee /etc/modules-load.d/containerd.conf <<EOF
overlay
br_netfilter
EOF
sudo modprobe overlay
sudo modprobe br_netfilter

sudo tee /etc/sysctl.d/99-kubernetes-k8s.conf <<EOF
net.bridge.bridge-nf-call-iptables  = 1
net.ipv4.ip_forward                 = 1
EOF
sudo sysctl --system

安装容器运行时（Docker）

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
echo "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker

安装 kubeadm、kubelet、kubectl

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

以上步骤完成后，所有节点应已具备容器运行环境与 Kubernetes 基础组件，且完成必要的内核与网络调优。

三初始化控制平面

初始化集群（单主示例）
```
sudo kubeadm init --pod-network-cidr=10.244.0.0/16
```
说明：
- 如使用 Flannel，Pod 网段 10.244.0.0/16 是推荐值；如使用 Calico，常见为 192.168.0.0/16（需与 Calico 清单一致）。
- 初始化成功后，终端会输出 kubeadm join 命令，请妥善保存。

配置 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

验证控制平面

kubectl cluster-info
kubectl get nodes
kubectl get pods -n kube-system

等待数分钟，控制平面与系统 Pod 就绪后，节点状态应变为 Ready。

四加入工作节点

在工作节点执行初始化时输出的 kubeadm join 命令，例如：

sudo kubeadm join <MASTER_IP>:6443 \
  --token <TOKEN> \
  --discovery-token-ca-cert-hash sha256:<HASH>

如令牌过期，可在控制平面重新生成：
```
kubeadm token create --print-join-command
```
回到控制平面验证：
```
kubectl get nodes
```

所有加入节点就绪后，集群即具备基本的调度与网络能力。

五常见问题与优化

镜像拉取缓慢或失败：可使用国内镜像仓库（如 registry.aliyuncs.com/google_containers）替换 kubeadm 默认仓库，或在 kubeadm 初始化时通过 –image-repository 指定；也可提前在各节点手动拉取所需镜像。
防火墙/安全组：确保节点间开放 6443、10250、10251、10252、2379、2380、8472/udp 等端口，或测试环境临时关闭防火墙。
容器运行时选择：除 Docker 外，也可使用 containerd（生产常用，资源开销更低）；若使用 containerd，需按官方指引完成配置与 CRI 启用。
节点 NotReady：优先检查 kubelet 服务状态、CNI 网络插件是否成功部署、以及 Pod CIDR 是否与网络插件配置一致。
克隆/虚拟化环境：确保 MAC 地址 与 product_uuid 唯一，避免 kubelet 误判为同一节点。

最新问答

相关标签