Ubuntu部署Kubernetes时遇到问题怎么办

Ubuntu部署Kubernetes排错速查手册

一 快速自检清单

• 关闭并永久禁用 swap：执行 swapoff -a，并将 /etc/fstab 中的 swap 行注释；Kubernetes 运行时不支持启用 swap。
• 唯一性校验：确保各节点 MAC 地址 与 product_uuid 唯一，避免节点识别冲突。
• 内核与转发：加载模块 br_netfilter、bridge，并开启桥接流量转发与 IPv4 转发：
  • 模块：modprobe br_netfilter bridge
  • sysctl：net.bridge.bridge-nf-call-ip6tables=1、net.bridge.bridge-nf-call-iptables=1、net.ipv4.ip_forward=1
• 容器运行时与 cgroup 驱动：推荐使用 containerd；将其 cgroup 驱动设为 systemd，否则 kubeadm init 可能失败。
• 软件源与版本：添加 Kubernetes APT 仓库，安装并锁定 kubeadm/kubelet/kubectl 的同一小版本；控制平面与 kubelet 版本差异不超过 1 个次要版本，且 kubelet 版本不可高于 API Server。
• 主机互通与端口：核对节点间 IP 互通 与 所需端口开放（如 6443、10250、2379、2380、10251、10252、10255 等）；Ubuntu 上可临时 ufw disable --now 做验证。
• 镜像拉取：若无法拉取 gcr.io 镜像，使用国内仓库并在需要时重打标签（如 registry.aliyuncs.com/google_containers/... → k8s.gcr.io/...）。

二 常见报错与修复

• 预检失败：提示 “running with swap on is not supported”
  处理：执行 swapoff -a 并注释 /etc/fstab 中的 swap 行，重启后验证 free -h。
• kubelet 健康检查失败：访问 10248 端口被拒绝
  处理：将 containerd 的 cgroup 驱动设为 systemd，重启 containerd 与 kubelet：
  • /etc/docker/daemon.json 中加入：{"exec-opts": ["native.cgroupdriver=systemd"]}
  • 执行：systemctl daemon-reload && systemctl restart containerd && systemctl restart kubelet
• 节点加入失败或 NotReady
  处理：核对 hostname/IP、节点到控制面的 网络连通性、kubelet 服务状态；必要时 kubeadm reset 后重新 kubeadm join。
• kubectl 找不到或无法连接
  处理：确认 kubectl 已安装且版本匹配，在用户目录配置 kubeconfig：mkdir -p $HOME/.kube && sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config && sudo chown $(id -u):$(id -g) $HOME/.kube/config，或设置 export KUBECONFIG=$HOME/.kube/config。
• Pod 无法启动
  处理：kubectl describe pod <name> 查看事件；检查 镜像可用性、资源配额、安全策略 与 网络插件 是否已部署。
• 镜像拉取失败
  处理：使用国内镜像源（如 registry.aliyuncs.com/google_containers），必要时 docker tag 重命名后再 kubeadm init。
• GPG 签名错误（NO_PUBKEY）
  处理：导入缺失公钥（示例：apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys FEEA9169307EA071）或改用新版签名方式将密钥保存至 /etc/apt/keyrings/。

三 初始化与网络插件部署要点

• 初始化命令示例：
  • kubeadm init --kubernetes-version=v1.24.17 --image-repository registry.aliyuncs.com/google_containers
  • 按需设置 --apiserver-advertise-address、--service-cidr、--pod-network-cidr。
• 获取加入命令：
  • 查看：kubeadm token create --print-join-command
  • 若遗失：在控制面节点重新生成并打印加入命令。
• 安装网络插件：
  • Flannel 示例：kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
  • 若域名解析失败，可在 /etc/hosts 临时添加 185.199.108.133 raw.githubusercontent.com 再执行。
• 节点上使用 kubectl：
  • 将控制面节点的 /etc/kubernetes/admin.conf 复制到工作节点的 $HOME/.kube/config，或设置 KUBECONFIG 环境变量。

四 日志与诊断命令

• 查看 kubelet 日志：journalctl -xeu kubelet（定位节点级问题首选）。
• 查看控制面容器日志：
  • crictl ps -a 列出容器
  • crictl logs <container-id> 查看具体日志
• 集群状态与事件：
  • kubectl get nodes -o wide
  • kubectl get pods -A -o wide
  • kubectl describe node <node>、kubectl describe pod <pod>
• 重置与重试：
  • kubeadm reset -f，修正根因后重新 kubeadm init 或 kubeadm join。

五 一键最小复现环境建议

• 准备 2–3 台 Ubuntu（建议 2 核 CPU / 2 GB 内存 / 20 GB 磁盘 以上），主机名与 IP 固定且可互通。
• 按“快速自检清单”完成系统配置；安装并锁定同一小版本的 kubeadm/kubelet/kubectl。
• 使用 containerd 并将 cgroup 驱动设为 systemd；按需配置国内镜像源。
• 初始化控制面后安装 Flannel，再用 kubeadm join 加入工作节点；最后用 kubectl get nodes 确认 Ready 状态。