k8s各种场景下排错思路以及命令 k8s常见问题故障处理思路

Kubernetes 集群故障通常集中在 Pod 异常、Service/网络不通、存储挂载失败、节点状态异常、配置错误 等场景。以下按错误环境分类，梳理排错思路、常见原因及对应命令，覆盖 90% 生产/测试环境问题。

一、Pod 异常环境（最常见）

现象：Pod 处于 Pending、CrashLoopBackOff、ImagePullBackOff、Terminating等状态，无法正常运行。

1. Pod 处于 Pending状态（调度失败）

可能原因：资源不足（CPU/内存/存储）、调度约束（亲和性/反亲和性）、PVC 未绑定、节点标签不匹配。

排查思路：

• 检查 Pod 事件（Events）中的调度失败原因；
• 查看节点资源是否充足；
• 检查调度约束（如 nodeSelector、affinity）是否匹配节点标签。

关键命令：

# 1. 查看 Pod 详细事件（核心！）
kubectl describe pod <pod-name> [-n <namespace>] | grep -A 20 "Events:"# 示例输出关键信息：
# Events:
#   Type     Reason            Age   From               Message
#   ----     ------            ----  ----               -------
#   Warning  FailedScheduling  2m    default-scheduler  0/3 nodes are available: 3 Insufficient cpu.# 2. 检查节点资源使用（需 metrics-server）
kubectl top nodes  # 查看节点 CPU/内存使用率
kubectl describe nodes | grep -A 10 "Allocatable"  # 查看节点可分配资源# 3. 检查调度约束（如 nodeSelector）
kubectl get pod <pod-name> -o jsonpath='{.spec.nodeSelector}'
kubectl get nodes --show-labels | grep <label-key>  # 检查节点是否匹配标签# 4. 检查 PVC 是否绑定（若 Pod 挂载 PVC）
kubectl get pvc [-n <namespace>]  # 查看 PVC 状态是否为 Bound

2. Pod 处于 CrashLoopBackOff状态（反复重启）

可能原因：应用启动失败（配置错误、依赖缺失）、健康检查（liveness/readiness probe）未通过、容器退出码非 0。

排查思路：

• 查看容器日志（定位应用层错误）；
• 检查健康检查配置是否合理；
• 进入容器手动执行启动命令，验证环境。

关键命令：

# 1. 查看容器日志（实时追踪 + 历史日志）
kubectl logs -f <pod-name> [-c <container-name>] [-n <namespace>]  # 实时日志
kubectl logs --previous <pod-name> [-c <container-name>] [-n <namespace>]  # 上一次启动日志（重启前）# 示例：查看 Nginx 容器日志是否有 404/502 错误
kubectl logs -f my-nginx -c nginx -n web# 2. 检查健康检查配置
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].livenessProbe}'
# 若配置不当（如端口错误、路径不存在），会导致容器被重启# 3. 进入容器手动调试（验证环境变量、依赖）
kubectl exec -it <pod-name> -- sh  # 进入容器 Shell
# 手动执行启动命令（如查看配置文件是否存在）
cat /etc/nginx/nginx.conf
curl http://localhost:80  # 测试应用是否能本地访问

3. Pod 处于 ImagePullBackOff状态（镜像拉取失败）

可能原因：镜像名称错误、镜像仓库认证失败（私有仓库）、网络无法访问镜像仓库。

排查思路：

• 检查镜像名称和 tag 是否正确；
• 验证私有仓库认证（Secret 是否正确绑定）；
• 测试节点/集群能否访问镜像仓库（如 Docker Hub、Harbor）。

关键命令：

# 1. 查看 Pod 事件（确认镜像拉取错误细节）
kubectl describe pod <pod-name> | grep -A 10 "Events:"
# 示例错误："Failed to pull image \"my-private-repo/app:v1\": rpc error: code = Unknown desc = Error response from daemon: pull access denied"# 2. 检查镜像名称和 tag（YAML 中 image 字段）
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].image}'# 3. 测试镜像拉取（在节点上手动执行，需 Docker 环境）
docker pull <image-name>:<tag>  # 如 docker pull nginx:latest# 4. 检查私有仓库 Secret（若使用私有仓库）
kubectl get secret -n <namespace> | grep registry  # 查看是否存在 registry-secret
kubectl describe secret <registry-secret> -n <namespace>  # 检查认证信息是否正确

二、Service/网络不通环境

现象：Pod 间无法通信、外部无法访问 Service、DNS 解析失败。

1. Service 无法访问（外部/内部）

可能原因：Service 类型配置错误（如 LoadBalancer 未分配 IP、NodePort 端口未开放）、Endpoint 为空（selector 不匹配）、网络策略限制。

排查思路：

• 检查 Service 的 Endpoints是否存在（确认流量能路由到 Pod）；
• 验证 Service 端口映射（port/targetPort/nodePort）；
• 检查防火墙/安全组/网络策略是否放行流量。

关键命令：

# 1. 查看 Service 详情（端口映射、selector）
kubectl describe svc <svc-name> [-n <namespace>]
# 关键字段：Ports（port/targetPort/nodePort）、Selector（是否匹配 Pod 标签）# 2. 查看 Endpoint（确认是否有 Pod IP）
kubectl get endpoints <svc-name> [-n <namespace>]
# 若 Endpoints 为空：① selector 标签不匹配；② Pod 未 Running；③ Pod 未通过 readinessProbe# 3. 测试 Service 访问（从集群内部）
kubectl exec -it <any-pod> -- curl http://<svc-cluster-ip>:<port>  # ClusterIP 访问
kubectl exec -it <any-pod> -- curl http://<node-ip>:<nodePort>  # NodePort 访问# 4. 检查网络策略（是否限制流量）
kubectl get networkpolicy [-n <namespace>]  # 列出所有网络策略
kubectl describe networkpolicy <np-name> [-n <namespace>]  # 查看允许的 IP/端口

2. 外部无法访问 LoadBalancer Service

可能原因：MetalLB/IP 分配失败、NodePort 未开放、防火墙拦截、BGP 路由未配置（若用 BGP 模式）。

排查思路：

• 检查 LoadBalancer 的 EXTERNAL-IP是否分配（非 <pending>）；
• 验证节点防火墙是否开放 NodePort 或 LoadBalancer 端口；
• 检查 MetalLB 配置（IP 池、网络模式）。

关键命令：

# 1. 查看 LoadBalancer Service 状态
kubectl get svc <svc-name> [-n <namespace>]
# 关键字段：EXTERNAL-IP（是否分配）、PORT(S)（外部端口）# 2. 测试节点端口访问（若为 NodePort/LoadBalancer）
curl http://<node-ip>:<nodePort>  # 替换为实际节点 IP 和端口# 3. 检查节点防火墙（以 firewalld 为例）
sudo firewall-cmd --list-ports | grep <nodePort>  # 查看端口是否开放
sudo firewall-cmd --add-port=<nodePort>/tcp --permanent && sudo firewall-cmd --reload  # 开放端口

3. Pod 间网络不通

可能原因：网络插件异常（Calico/Cilium/Flannel）、网络策略限制、节点路由问题。

排查思路：

• 检查网络插件 Pod 是否正常运行；
• 测试 Pod 间连通性；
• 查看网络策略是否放行。

关键命令：

# 1. 检查网络插件状态（以 Calico 为例）
kubectl get pods -n kube-system -l k8s-app=calico-node  # 所有 Pod 需为 Running
kubectl logs -n kube-system <calico-pod-name> | grep -i "error"  # 查看插件日志# 2. 测试 Pod 间连通性（获取两个 Pod IP）
POD1_IP=$(kubectl get pod <pod1> -o jsonpath='{.status.podIP}')
POD2_IP=$(kubectl get pod <pod2> -o jsonpath='{.status.podIP}')
kubectl exec <pod1> -- curl -I http://$POD2_IP:80  # 从 Pod1 访问 Pod2# 3. 检查路由表（在节点上执行）
ip route show  # 查看是否有到其他节点 Pod 网段的路由（由网络插件配置）

4. DNS 解析失败

现象：Pod 内无法解析 Service 名称（如 nslookup my-svc.my-namespace.svc.cluster.local失败）。

可能原因：CoreDNS/Kube-DNS 异常、Pod /etc/resolv.conf配置错误。

关键命令：

# 1. 检查 CoreDNS 状态
kubectl get pods -n kube-system -l k8s-app=kube-dns  # 所有 Pod 需为 Running
kubectl logs -n kube-system <coredns-pod-name> | grep -i "error"  # 查看 DNS 日志# 2. 在 Pod 内测试 DNS 解析
kubectl exec <pod-name> -- nslookup <svc-name>.<namespace>.svc.cluster.local
# 示例：nslookup my-nginx.web.svc.cluster.local# 3. 检查 Pod 的 /etc/resolv.conf
kubectl exec <pod-name> -- cat /etc/resolv.conf
# 正常应包含 nameserver 10.96.0.10（Cluster DNS IP）和 search 域

三、存储异常环境

现象：Pod 无法挂载 PVC、数据无法持久化、PVC 处于 Pending状态。

1. PVC 处于 Pending状态（未绑定 PV）

可能原因：StorageClass 未配置、PV 不足、PVC 请求参数（如 accessMode、storage）与 PV 不匹配。

排查思路：

• 检查 PVC 事件（Events）中的绑定失败原因；
• 验证 StorageClass 是否存在且配置正确；
• 检查 PV 是否满足 PVC 的请求（容量、accessMode）。

关键命令：

# 1. 查看 PVC 详情
kubectl describe pvc <pvc-name> [-n <namespace>]
# 关键字段：Status（Pending）、Events（错误信息，如 "no persistent volumes available for this claim"）# 2. 检查 StorageClass
kubectl get storageclass  # 查看是否存在 PVC 指定的 StorageClass
kubectl describe storageclass <sc-name>  # 检查 provisioner（如 csi-hostpath）是否正常# 3. 检查 PV（动态供应的 PV 由 StorageClass 自动创建）
kubectl get pv  # 查看是否有 PV 状态为 Bound 且容量/模式匹配 PVC

2. Pod 无法挂载卷（MountVolume 失败）

可能原因：存储卷权限不足（如 MinIO 数据目录 UID 不匹配）、存储插件异常、卷类型不支持。

排查思路：

• 进入 Pod 查看挂载点是否正常；
• 检查存储卷权限（如容器用户 UID 是否有读写权限）；
• 查看 kubelet 日志是否有卷挂载错误。

关键命令：

# 1. 查看 Pod 挂载信息
kubectl get pod <pod-name> -o jsonpath='{.spec.volumes[*].persistentVolumeClaim.claimName}'
kubectl describe pod <pod-name> | grep -A 10 "Mounts:"  # 查看挂载点和卷名称# 2. 进入 Pod 检查挂载目录
kubectl exec -it <pod-name> -- df -h /<mount-path>  # 查看磁盘空间和使用
ls -ld /<mount-path>  # 检查目录权限（如 MinIO 需 UID 1000 可写）# 3. 查看 kubelet 日志（节点上执行）
journalctl -u kubelet | grep -i "mount"  # 过滤卷挂载错误（如 "MountVolume.SetUp failed"）

四、节点异常环境

现象：节点状态 NotReady、Pod 无法调度到节点、kubelet 异常。

1. 节点处于 NotReady状态

可能原因：kubelet 服务崩溃、节点资源耗尽（DiskPressure/MemoryPressure）、网络与控制平面断开。

排查思路：

• 查看节点状态详情（Conditions）；
• 检查 kubelet 服务是否运行；
• 验证节点与 API Server 通信是否正常。

关键命令：

# 1. 查看节点状态
kubectl get nodes
kubectl describe node <node-name>  # 查看 Conditions（如 MemoryPressure、DiskPressure）# 2. 检查 kubelet 服务状态（节点上执行）
systemctl status kubelet  # 查看是否 Active: running
journalctl -u kubelet -f  # 实时查看 kubelet 日志（核心！）
journalctl -u kubelet | grep -i "error"  # 过滤错误# 3. 在节点上测试访问 API Server（确保节点与控制平面通信正常）
curl -k https://<api-server-ip>:6443/version  # 需证书或跳过 TLS

2. 节点资源不足（DiskPressure/MemoryPressure）

现象：节点状态显示 DiskPressure或 MemoryPressure，Pod 被驱逐。

排查思路：

• 清理节点磁盘空间（如删除无用镜像、日志）；
• 扩容节点资源或迁移 Pod 到其他节点。

关键命令：

# 1. 查看节点资源压力详情
kubectl describe node <node-name> | grep -A 10 "Conditions:"# 2. 清理节点 Docker 镜像（节点上执行，若用 Docker）
docker system prune -af  # 清理无用镜像、容器、卷# 3. 驱逐 Pod（手动迁移，谨慎操作）
kubectl drain <node-name> --ignore-daemonsets  # 驱逐节点上所有 Pod（除 DaemonSet）

五、配置错误环境

现象：YAML 语法错误、资源定义冲突、环境变量/命令配置错误。

1. YAML 语法错误（kubectl apply失败）

可能原因：缩进错误、字段拼写错误、非法字符。

排查思路：

• 使用 dry-run校验 YAML；
• 对比官方文档或已有正确 YAML。

关键命令：

# 校验 YAML 语法（不提交到集群）
kubectl apply -f <yaml-file> --dry-run=client
# 示例错误："error: error validating \"nginx.yaml\": error validating data: [ValidationError(Deployment.spec.template.spec.containers[0]): missing required field \"image\" in io.k8s.api.core.v1.Container]"

2. 环境变量/命令配置错误（Pod 启动失败）

可能原因：环境变量未注入、容器启动命令（command）错误、args 参数不匹配。

排查思路：

• 查看 Pod 描述中的环境变量和命令配置；
• 进入容器手动执行命令验证。

关键命令：

# 1. 查看 Pod 环境变量
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].env}'# 2. 查看容器启动命令（command/args）
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].command}'
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].args}'# 3. 进入容器手动执行命令
kubectl exec -it <pod-name> -- <command>  # 如 /app/start.sh

六、通用排错流程总结

1. 确认问题现象：明确故障表现（Pod 异常/网络不通/存储失败等）。
2. 定位受影响资源：通过 kubectl get列出相关资源（Pod/Service/Node 等）。
3. 查看资源状态和事件：kubectl describe和 kubectl logs是核心，关注 Events 和日志中的 error/warning。
4. 检查关联资源：如 Service → Endpoint、Pod → PVC、Node → kubelet。
5. 验证配置和环境：YAML 语法、网络连通性、存储权限、资源充足性。
6. 逐步排除：从应用层（日志）→ 组件层（kubelet/CoreDNS）→ 基础设施层（节点/网络/存储）。

通过以上分类和命令，可快速定位 K8s 集群中 90% 以上的常见故障，关键是结合“事件+日志+配置”三要素进行排查。