K8s集群组件启动不成功排查

一、基本信息收集
二、分层排查流程
- [2.1 基础环境检查](#2.1 基础环境检查)
- [2.2 容器运行时检查](#2.2 容器运行时检查)
- - [2.2.1 containerd](#2.2.1 containerd)
  - [2.2.2 docker](#2.2.2 docker)
  - [2.2.3 清理所有残留资源](#2.2.3 清理所有残留资源)
- [2.3 Kubelet 日志分析](#2.3 Kubelet 日志分析)
- [2.4 具体组件排查](#2.4 具体组件排查)
- - [2.4.1 API Server 故障](#2.4.1 API Server 故障)
  - [2.4.2 Controller Manager/Scheduler 故障](#2.4.2 Controller Manager/Scheduler 故障)
  - [2.4.3 etcd 故障](#2.4.3 etcd 故障)
  - [2.4.4 网络插件故障（CNI）](#2.4.4 网络插件故障（CNI）)
- [2.5 证书和认证检查](#2.5 证书和认证检查)
三、常见问题及解决方案
- [3.1 证书相关错误](#3.1 证书相关错误)
- [3.2 镜像拉取失败](#3.2 镜像拉取失败)
- [3.3 端口占用冲突](#3.3 端口占用冲突)
- [3.4 资源不足](#3.4 资源不足)
四、诊断工具
五、快速恢复指南
- [5.1 单节点集群恢复](#5.1 单节点集群恢复)
- [5.2 多节点集群恢复顺序](#5.2 多节点集群恢复顺序)
六、预防措施
七、关键日志位置

一、基本信息收集

bash 复制代码

# 1. 查看节点状态
kubectl get nodes
kubectl describe node <node-name>

# 2. 查看组件状态（取决于你的安装方式）
# 如果是kubeadm
kubectl get pods -n kube-system

# 3. 查看服务状态（如果是系统服务）
systemctl status kubelet
systemctl status docker/containerd

二、分层排查流程

2.1 基础环境检查

bash 复制代码

# 1. 主机资源
free -h      # 内存
df -h        # 磁盘空间
top/htop     # CPU负载

# 2. 内核参数
sysctl net.ipv4.ip_forward          # 应为1
sysctl net.bridge.bridge-nf-call-iptables  # 应为1

# 3. 时间同步
timedatectl status                  # NTP同步
date                                # 各节点时间一致性

2.2 容器运行时检查

2.2.1 containerd

shell 复制代码

# Containerd
ctr namespaces list
crictl ps -a
journalctl -u containerd -f

# 尝试强制启动 containerd（跳过依赖检查）
systemctl start containerd --force

# 再次检查 containerd 状态
systemctl status containerd

即使 systemctl status 仍显示 inactive，也可以直接检查进程是否存在（避免 systemd 状态误判）：

shell 复制代码

# 检查 containerd 进程是否真的在运行
ps -ef | grep containerd | grep -v grep

# 测试 containerd 功能（直接调用 ctr 工具）
ctr version

Docker 依赖 containerd、network.target 等服务，这些服务异常会导致启动卡住：

bash 复制代码

# 1. 检查并重启 containerd（Docker 核心依赖）
systemctl restart containerd
systemctl status containerd

# 2. 检查系统网络服务
systemctl restart network.target  # CentOS/RHEL
systemctl restart systemd-networkd  # Ubuntu/Debian

# 3. 强制重启 Docker（跳过依赖检查）
systemctl start docker --force

常见错误及解决：

错误 1：配置文件损坏
- 备份并重置 containerd 配置文件（默认路径 /etc/containerd/config.toml）：

shell 复制代码

mv /etc/containerd/config.toml /etc/containerd/config.toml.bak
containerd config default > /etc/containerd/config.toml
systemctl restart containerd

错误 2：系统内核参数不支持
- 检查并开启 overlayfs 内核模块（containerd 默认存储驱动依赖）：

shell 复制代码

modprobe overlay
echo "overlay" >> /etc/modules-load.d/containerd.conf

当 containerd 正常运行后，重新修复 Docker 和 kubelet 的状态：

shell 复制代码

# 1. 重启 Docker 服务
systemctl restart docker
docker info  # 验证 Docker 功能

# 2. 重启 kubelet 服务
systemctl restart kubelet
journalctl -u kubelet -f  # 查看 kubelet 启动日志

2.2.2 docker

先确保 Docker 正常运行 - 这是容器运行时的基础

bash 复制代码

# Docker
docker info
docker ps -a
journalctl -u docker -f

Docker 启动需要一定的内存和磁盘空间，资源不足会导致卡住：

bash 复制代码

# 1. 检查内存使用（可用内存低于 512MB 会卡住）
free -h

# 2. 检查磁盘空间（/var/lib/docker 所在分区使用率 >90% 会卡住）
df -h /var/lib/docker

# 3. 清理磁盘空间（比如删除无用镜像/容器）
# 如果 Docker 完全启动不了，直接清理 Docker 数据目录（注意：会删除所有镜像/容器，谨慎！）
# rm -rf /var/lib/docker/*

Docker 守护进程未运行会导致无法查看 kube-apiserver 容器

shell 复制代码

# 启动 Docker 守护进程
systemctl start docker

# 设置 Docker 开机自启（避免后续重启失效）
systemctl enable docker

# 验证 Docker 是否正常运行
systemctl status docker

如果启动 Docker 报错，先查看 Docker 日志定位问题：

bash 复制代码

journalctl -u docker -f  # 实时查看 Docker 日志

# 同时查看 Docker 自身的日志文件（备选）
tail -f /var/log/docker.log

检查是否正确启动：

shell 复制代码

# 检查 Docker 进程是否存在
ps -ef | grep dockerd | grep -v grep

# 直接测试 Docker 功能（最直观）
docker info  # 能输出信息说明 Docker 已正常运行
docker ps    # 查看容器列表，验证 Docker 可用

2.2.3 清理所有残留资源

如果手动启动也失败，先清理所有残留资源，彻底清理 Docker/containerd 残留（解决进程 / 锁占用）

shell 复制代码

# 1. 杀死所有 Docker/containerd 相关进程
pkill -9 dockerd containerd containerd-shim docker-proxy

# 2. 清理 Docker 所有锁文件、PID 文件、sock 文件
rm -rf /var/run/docker* /var/run/containerd*

# 3. 清理 Docker 存储目录（注意：会删除所有镜像/容器，谨慎！如果有重要数据先备份）
# mv /var/lib/docker /var/lib/docker.bak
# mkdir /var/lib/docker

# 4. 重置 Docker 配置（避免配置文件错误导致启动失败）
mv /etc/docker/daemon.json /etc/docker/daemon.json.bak
touch /etc/docker/daemon.json

2.3 Kubelet 日志分析

bash 复制代码

# 查看kubelet日志
journalctl -u kubelet -f --no-pager
journalctl -u kubelet --since "1 hour ago"

# 查看kubelet配置
cat /var/lib/kubelet/kubeadm-flags.env
cat /etc/systemd/system/kubelet.service.d/10-kubeadm.conf

2.4 具体组件排查

2.4.1 API Server 故障

shell 复制代码

# 检查apiserver pod/logs
kubectl describe pod kube-apiserver-<node> -n kube-system
kubectl logs kube-apiserver-<node> -n kube-system

# 直接测试API
curl -k https://localhost:6443/healthz
curl -k https://<master-ip>:6443/version

2.4.2 Controller Manager/Scheduler 故障

bash 复制代码

# 查看日志
kubectl logs <pod-name> -n kube-system -c kube-controller-manager
kubectl logs <pod-name> -n kube-system -c kube-scheduler

# 检查端口监听
netstat -tlnp | grep 10257  # controller-manager
netstat -tlnp | grep 10259  # scheduler

2.4.3 etcd 故障

bash 复制代码

# 检查etcd状态
kubectl describe pod etcd-<node> -n kube-system
kubectl logs etcd-<node> -n kube-system

# 使用etcdctl检查
ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  endpoint health

2.4.4 网络插件故障（CNI）

bash 复制代码

# 查看网络插件pod
kubectl get pods -n kube-system | grep -E 'flannel|calico|cilium|weave'

# 检查CNI配置
ls -la /etc/cni/net.d/
cat /etc/cni/net.d/*.conf

# 查看IP分配
ip addr show
ip route show

2.5 证书和认证检查

bash 复制代码

# 检查证书过期时间
openssl x509 -in /etc/kubernetes/pki/apiserver.crt -noout -dates
kubeadm certs check-expiration

# 检查kubeconfig
kubectl config view
kubectl get --raw=/healthz

三、常见问题及解决方案

3.1 证书相关错误

bash 复制代码

# 更新证书（kubeadm）
kubeadm certs renew all
systemctl restart kubelet

3.2 镜像拉取失败

bash 复制代码

# 查看镜像需求
kubeadm config images list

# 手动拉取镜像
docker pull <image-name>
# 或使用镜像仓库代理

3.3 端口占用冲突

bash 复制代码

# 检查端口占用
ss -tlnp | grep -E '6443|2379|10250'

# 查看进程
lsof -i :6443

3.4 资源不足

bash 复制代码

# 清理资源
kubeadm reset
docker system prune -a

# 检查磁盘inodes
df -i

四、诊断工具

bash 复制代码

# 1. 使用kubeadm诊断
kubeadm init phase preflight  # 预检
kubeadm config print init-defaults  # 查看默认配置

# 2. 集群诊断工具
kubectl cluster-info dump > cluster-dump.log

# 3. 网络诊断
kubectl run --image=busybox test -- sleep 3600
kubectl exec test -- nslookup kubernetes.default
kubectl exec test -- ping <pod-ip>

五、快速恢复指南

5.1 单节点集群恢复

bash 复制代码

# 1. 重启kubelet
systemctl daemon-reload
systemctl restart kubelet

# 2. 重启Docker/Containerd
systemctl restart docker

# 3. 重建静态Pod（如果使用kubeadm）
rm -f /etc/kubernetes/manifests/*.yaml
# 等待几秒后，复制yaml文件回来
cp /etc/kubernetes/manifests.bak/*.yaml /etc/kubernetes/manifests/

5.2 多节点集群恢复顺序

etcd集群 → 2. API Server → 3. Controller Manager → 4. Scheduler → 5. Worker节点

六、预防措施

启用监控：部署Prometheus+Grafana监控集群组件
日志收集：使用EFK/ELK收集组件日志

定期检查：

bash 复制代码

# 定期健康检查脚本
kubectl get componentstatuses
kubectl get --raw='/readyz?verbose'

备份关键数据：

bash 复制代码

# 备份etcd
ETCDCTL_API=3 etcdctl snapshot save backup.db
# 备份证书和配置
tar czf k8s-backup-$(date +%Y%m%d).tar.gz /etc/kubernetes/

七、关键日志位置

组件	日志位置
kubelet	`journalctl -u kubelet`
Docker	`/var/log/docker.log`
Containerd	`/var/log/containerd.log`
系统日志	`/var/log/messages` 或 `/var/log/syslog`
Pod日志	`kubectl logs <pod-name>`