Debian系统上Kubernetes部署的故障排除

Debian上Kubernetes部署的故障排除指南

一 快速定位流程

• 检查集群与控制面连通性：执行kubectl cluster-info与kubectl get nodes，确认控制面地址可达、节点状态是否为Ready。若节点NotReady，优先查看kubelet与网络插件状态。
• 查看系统组件日志：用journalctl -u kubelet -f实时跟踪kubelet；必要时查看kube-proxy与容器运行时日志，定位启动失败、证书、镜像拉取等根因。
• 校验基础运行条件：确认已关闭Swap（临时与永久）、防火墙/安全组已放行必要端口、节点间网络互通、系统**资源（CPU/内存/磁盘）**充足。
• 复核关键配置：确认kubeconfig路径与内容正确（如kubectl config view）、容器运行时（如containerd）运行正常、组件版本兼容。
• 若仍异常，导出诊断信息：节点上执行kubeadm init/join的**–v=6日志、相关Pod日志与describe**输出，便于进一步分析。

二 高频故障与修复

• 节点NotReady或kubelet异常

  • 典型原因：未关闭Swap、kubelet服务未运行或配置不当、容器运行时异常。
  • 处理：
    • 关闭Swap并持久化：执行swapoff -a，并在**/etc/fstab注释swap行；重启后确认cat /proc/swaps**为空。
    • 检查kubelet：sudo systemctl status kubelet；查看日志journalctl -u kubelet -f；必要时按日志修复cgroup/镜像/证书等问题。
    • 确认运行时：确保containerd已安装并运行（如sudo systemctl status containerd）。

• 端口与防火墙阻断

  • 常见被阻断端口：6443（APIServer）、2379/2380（etcd）、10250（kubelet）、10251/10252（kube-scheduler/controller-manager）、10255（kubelet只读）。
  • 处理：在UFW放行示例：sudo ufw allow 6443,2379,2380,10250,10251,10252,10255/tcp && sudo ufw reload；云环境同步放通安全组规则。

• 镜像拉取失败（ErrImagePull/ImagePullBackOff）

  • 典型原因：镜像名称错误、仓库不可达、私有仓库证书缺失。
  • 处理：核对镜像名与仓库；如使用私有仓库，在节点**/etc/docker/certs.d//ca.crt放置CA证书；必要时使用可访问的镜像仓库**或手动拉取并重命名镜像。

• 节点加入失败（kubeadm join 报错）

  • 典型原因：token过期、CA证书哈希不匹配、端口被占用、网络不通。
  • 处理：在主节点重新生成kubeadm token create --print-join-command；核对**–discovery-token-ca-cert-hash**；检查端口占用与节点间连通性后重试。

• 服务访问异常（证书/端口/类型/外部访问）

  • 证书问题：访问API或Ingress出现证书校验失败，更新服务端证书或在客户端使用**–cacert指定CA；生产环境不建议-k/–insecure**。
  • 端口与服务类型：核对Service port与容器containerPort一致；若需外部访问，将Service type设为NodePort/LoadBalancer而非ClusterIP。

• Pod间通信或DNS解析失败

  • 典型原因：网络插件未部署/异常、iptables/nftables规则冲突、网络策略限制、CoreDNS未就绪。
  • 处理：部署或重新部署网络插件（如Flannel）；检查并清理冲突规则；确认kubectl get pods -n kube-system -l k8s-app=coredns运行正常。

三 环境与配置核查清单

• 基础系统：确认CPU/内存/磁盘满足最低要求；系统时间与时区一致（容器内可用TZ=Asia/Shanghai环境变量统一时区）。
• 网络与安全：节点间互通；按需放行6443/2379/2380/10250/10251/10252/10255等端口；云上同步配置安全组。
• 运行时与组件：安装并运行containerd；安装kubelet/kubeadm/kubectl后执行apt-mark hold避免意外升级；确保组件版本兼容。
• kubeconfig与权限：家目录**~/.kube/config存在且路径正确（或设置KUBECONFIG**）；执行kubectl config view校验；必要时使用sudo或配置sudoers。

四 一键式命令参考

• 关闭Swap与持久化

sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab
cat /proc/swaps  # 应为空

• 放行常用端口（UFW）

sudo ufw allow 6443,2379,2380,10250,10251,10252,10255/tcp
sudo ufw reload

• 查看与跟踪组件状态

kubectl cluster-info
kubectl get nodes
kubectl get pods -A
sudo systemctl status kubelet
sudo journalctl -u kubelet -f

• 重新生成加入命令（主节点）

kubeadm token create --print-join-command

• 部署网络插件（示例：Flannel）

kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

• 外部访问服务（示例）

kubectl expose deployment nginx --type=NodePort --port=80
kubectl get svc nginx  # 获取NodePort并测试访问

以上命令覆盖了节点就绪、端口放行、日志排查、节点加入与网络插件部署的高频操作。