Debian系统Kubernetes安装常见问题解答

Debian 系统上部署 Kubernetes 的常见问题解答

一环境准备与系统要求

建议使用 Debian 12，并满足最低资源：2 核 CPU、2 GB 内存、20 GB 磁盘。所有节点之间需网络互通，主机名与 /etc/hosts 映射正确，时间与时区一致（如 Asia/Shanghai）。
关闭 Swap：临时执行 sudo swapoff -a，并注释 /etc/fstab 中的 swap 行，防止重启后恢复。
加载内核模块并开启桥接与转发：
- 模块：overlay、br_netfilter
- sysctl：net.bridge.bridge-nf-call-iptables=1、net.bridge.bridge-nf-call-ip6tables=1、net.ipv4.ip_forward=1
防火墙与安全组需放通 6443、2379、2380、10250、10251、10252、10255 等端口（或临时关闭防火墙用于排障）。

二容器运行时选择与安装

运行时选择
- Kubernetes ≥1.24 起内置的 dockershim 已移除，推荐直接使用 containerd；若必须使用 Docker，需额外安装 cri-dockerd 适配。
安装 containerd（推荐）
- 安装与启用：sudo apt install -y containerd && sudo systemctl enable --now containerd
- 生成默认配置并启用 CRI：sudo mkdir -p /etc/containerd && containerd config default | sudo tee /etc/containerd/config.toml && sudo systemctl restart containerd
安装 Docker + cri-dockerd（备选）
- 按官方仓库安装 Docker，随后安装并启用 cri-dockerd，确保 kubelet 通过 cri-dockerd 对接 Docker。

三 APT 源与版本兼容

新版仓库配置（解决 “仓库 … kubernetes-xenial Release 没有 Release 文件”）
- 删除旧源：sudo rm /etc/apt/sources.list.d/kubernetes.list
- 下载密钥：curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-archive-keyring.gpg
- 写入新源：echo "deb [signed-by=/etc/apt/keyrings/kubernetes-archive-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list
- 安装组件：sudo apt update && sudo apt install -y kubeadm=1.28.* kubelet=1.28.* kubectl=1.28.*
- 锁定版本：sudo apt-mark hold kubelet kubeadm kubectl
版本兼容要点
- 建议 kubelet 与 API Server 相差不超过 1 个次版本，且 kubelet 版本不可高于 API Server。
- 在 Debian 11 上使用较新 K8s 版本可能遇到更多兼容性问题，优先选择 Debian 12。

四初始化与网络插件

初始化控制平面
- 示例：sudo kubeadm init --pod-network-cidr=10.244.0.0/16（如使用 Flannel，该 CIDR 为推荐值）。
- 配置 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/tigera-operator.yaml && kubectl apply -f https://docs.projectcalico.org/manifests/custom-resources.yaml
加入工作节点
- 使用 kubeadm init 输出中的 kubeadm join … 命令在各节点执行。

五常见报错与快速排查

镜像拉取失败
- 现象：kubeadm init 阶段卡在拉取镜像。
- 处理：使用 kubeadm config images list 查看所需镜像，配置国内镜像源或手动 docker pull 并重命名标签后再初始化。
节点 NotReady
- 现象：kubectl get nodes 显示 NotReady。
- 处理：确认网络插件已安装且 Pod CIDR 与插件配置一致；检查 CNI 网桥与路由；查看 kubelet 与容器运行时日志。
端口或防火墙阻断
- 现象：节点无法加入或组件异常。
- 处理：放通 6443、2379、2380、10250、10251、10252、10255 等端口，或临时关闭防火墙验证。
证书或 kubeconfig 错误
- 现象：kubectl 报证书/权限/配置错误。
- 处理：确认 /etc/kubernetes/admin.conf 已正确拷贝至 $HOME/.kube/config，检查 RBAC 与证书有效期。
日志与诊断命令
- 系统日志：sudo journalctl -xeu kubelet、tail -f /var/log/syslog、dmesg
- 集群与组件：kubectl cluster-info、kubectl get nodes -o wide、kubectl logs -n kube-system <pod>。

最新问答