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>。