Kubernetes 故障排查命令大全：从诊断到修复（重写版）

Kubernetes 故障排查命令大全：从诊断到修复

Kubernetes 作为容器编排的事实标准，在生产环境中的故障排查能力是运维和开发人员的核心技能。本文基于 Kubernetes 官方文档和实战经验，整理了一套完整的故障排查命令手册，涵盖集群、Pod、网络、存储、节点等各类故障场景。

📋 使用说明

重要提示：本文中的命令包含占位符，使用时请替换为实际值！

命令示例说明：

• 原始命令模板：kubectl get pods -n <namespace>
• 实际使用：kubectl get pods -n default

一、快速诊断命令

1.1 集群整体状态

# 查看集群组件状态
kubectl get componentstatuses
kubectl get cs

# 查看集群信息
kubectl cluster-info

# 查看 API Server 健康状态
kubectl get --raw='/readyz?verbose'
kubectl get --raw='/healthz?verbose'

# 查看节点状态
kubectl get nodes
kubectl get nodes -o wide

输出示例：

NAME           STATUS   ROLES           AGE   VERSION
master-01      Ready    control-plane   365d  v1.28.4
worker-01      Ready              365d  v1.28.4
worker-02      Ready              365d  v1.28.4

1.2 命名空间资源概览

# 查看所有命名空间
kubectl get namespaces

# 查看特定命名空间的资源（<namespace> 替换为实际的命名空间名）
kubectl get all -n <namespace>

# 示例：查看 default 命名空间的所有资源
kubectl get all -n default

# 示例：查看 kube-system 命名空间的所有资源
kubectl get all -n kube-system

# 查看资源使用量
kubectl top nodes
kubectl top pods -n <namespace>

# 示例：查看 default 命名空间的 Pod 资源使用
kubectl top pods -n default

1.3 事件查看

# 查看当前命名空间事件
kubectl get events --sort-by='.lastTimestamp'

# 查看所有命名空间事件
kubectl get events -A --sort-by='.lastTimestamp'

# 查看特定 Pod 的事件（<pod-name> 和 <namespace> 替换为实际值）
kubectl describe pod <pod-name> -n <namespace>

# 示例：查看 nginx-deployment-abc123 Pod 的事件（在 default 命名空间）
kubectl describe pod nginx-deployment-abc123 -n default

# 实时监控事件
kubectl get events -w

1.4 故障定位流程

# 故障排查标准流程
kubectl get nodes              # → 检查节点状态
kubectl get pods -n <namespace>  # → 检查 Pod 状态
kubectl describe <resource> <name>  # → 查看详细事件
kubectl logs <pod-name> -n <namespace>  # → 查看容器日志
kubectl exec -it <pod-name> -n <namespace> -- /bin/bash  # → 进入容器排查

二、Pod 故障排查

2.1 Pod 状态检查

# 查看 Pod 列表（<namespace> 替换为实际的命名空间名）
kubectl get pods -n <namespace>

# 示例：查看 default 命名空间的所有 Pod
kubectl get pods -n default

# 查看 Pod 详细信息
kubectl get pods -o wide -n <namespace>

# 示例：查看 default 命名空间的 Pod 详细信息
kubectl get pods -o wide -n default

# 查看 Pod 的 YAML 配置（<pod-name> 和 <namespace> 替换为实际值）
kubectl get pod <pod-name> -o yaml -n <namespace>

# 示例：查看 nginx-deployment-abc123 Pod 的配置（在 default 命名空间）
kubectl get pod nginx-deployment-abc123 -o yaml -n default

# 查看 Pod 的标签
kubectl get pods --show-labels -n <namespace>

# 示例：查看 default 命名空间 Pod 的标签
kubectl get pods --show-labels -n default

2.2 Pod 状态说明

2.3 Pod 无法启动排查

步骤 1：查看 Pod 详情

# 查看详细信息（<pod-name> 和 <namespace> 替换为实际值）
kubectl describe pod <pod-name> -n <namespace>

# 示例：查看 nginx-deployment-abc123 的详情（在 default 命名空间）
kubectl describe pod nginx-deployment-abc123 -n default

# 重点关注：
# - Events 部分的事件信息
# - State 和 Last State 的退出码
# - Conditions 的状态

步骤 2：查看容器日志

# 查看主容器日志（<pod-name> 和 <namespace> 替换为实际值）
kubectl logs <pod-name> -n <namespace>

# 示例：查看 nginx-deployment-abc123 的日志（在 default 命名空间）
kubectl logs nginx-deployment-abc123 -n default

# 查看指定容器日志（多容器 Pod）
kubectl logs <pod-name> -c <container-name> -n <namespace>

# 示例：查看 my-pod 中 app 容器的日志（在 default 命名空间）
kubectl logs my-pod -c app -n default

# 查看之前的日志（容器重启后）
kubectl logs <pod-name> -p -n <namespace>

# 示例：查看 nginx-deployment-abc123 的重启前日志
kubectl logs nginx-deployment-abc123 -p -n default

# 实时查看日志
kubectl logs -f <pod-name> -n <namespace>

# 示例：实时查看 nginx-deployment-abc123 的日志
kubectl logs -f nginx-deployment-abc123 -n default

# 查看最近 100 行日志
kubectl logs --tail=100 <pod-name> -n <namespace>

# 示例：查看 nginx-deployment-abc123 最近 100 行日志
kubectl logs --tail=100 nginx-deployment-abc123 -n default

步骤 3：进入容器排查

# 进入容器 shell（<pod-name> 和 <namespace> 替换为实际值）
kubectl exec -it <pod-name> -n <namespace> -- /bin/bash
kubectl exec -it <pod-name> -n <namespace> -- /bin/sh

# 示例：进入 nginx-deployment-abc123 容器（在 default 命名空间）
kubectl exec -it nginx-deployment-abc123 -n default -- /bin/bash

# 在容器中执行命令
kubectl exec <pod-name> -n <namespace> -- ps aux
kubectl exec <pod-name> -n <namespace> -- env

# 示例：查看 nginx-deployment-abc123 容器的进程
kubectl exec nginx-deployment-abc123 -n default -- ps aux

# 查看容器内文件系统
kubectl exec <pod-name> -n <namespace> -- ls -la /app

# 示例：查看 nginx-deployment-abc123 容器的文件
kubectl exec nginx-deployment-abc123 -n default -- ls -la /app

2.4 CrashLoopBackOff 排查

# 1. 查看退出码（<pod-name> 和 <namespace> 替换为实际值）
kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[0].lastState.terminated.exitCode}' -n <namespace>

# 示例：查看 nginx-deployment-abc123 的退出码（在 default 命名空间）
kubectl get pod nginx-deployment-abc123 -o jsonpath='{.status.containerStatuses[0].lastState.terminated.exitCode}' -n default

# 2. 查看退出原因
kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[0].lastState.terminated.reason}' -n <namespace>

# 3. 查看日志
kubectl logs <pod-name> -p -n <namespace>

# 4. 检查资源限制
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].resources}' -n <namespace>

常见退出码：

2.5 ImagePullBackOff 排查

# 1. 查看详细描述（<pod-name> 和 <namespace> 替换为实际值）
kubectl describe pod <pod-name> -n <namespace>

# 2. 检查镜像名称
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].image}' -n <namespace>

# 3. 手动拉取镜像测试
docker pull <image-name>

# 4. 检查镜像拉取密钥
kubectl get secrets -n <namespace>
kubectl describe secret <secret-name> -n <namespace>

三、Deployment 故障排查

3.1 Deployment 状态检查

# 查看 Deployment 列表（<namespace> 替换为实际的命名空间名）
kubectl get deployments -n <namespace>

# 示例：查看 default 命名空间的所有 Deployment
kubectl get deployments -n default

# 查看 Deployment 详情（<deployment-name> 和 <namespace> 替换为实际值）
kubectl describe deployment <deployment-name> -n <namespace>

# 示例：查看 nginx Deployment 的详情（在 default 命名空间）
kubectl describe deployment nginx -n default

# 查看 ReplicaSet
kubectl get rs -n <namespace>

# 查看 Pod 列表（按 Deployment 筛选）
kubectl get pods -l app=<deployment-name> -n <namespace>

# 示例：查看 nginx Deployment 的所有 Pod（在 default 命名空间）
kubectl get pods -l app=nginx -n default

3.2 Deployment 无法更新

# 1. 查看 rollout 状态（<deployment-name> 和 <namespace> 替换为实际值）
kubectl rollout status deployment/<deployment-name> -n <namespace>

# 2. 查看 rollout 历史
kubectl rollout history deployment/<deployment-name> -n <namespace>

# 3. 回滚到上一个版本
kubectl rollout undo deployment/<deployment-name> -n <namespace>

# 4. 回滚到指定版本
kubectl rollout undo deployment/<deployment-name> --to-revision=2 -n <namespace>

# 5. 暂停/继续 rollout
kubectl rollout pause deployment/<deployment-name> -n <namespace>
kubectl rollout resume deployment/<deployment-name> -n <namespace>

3.3 Pod 无法达到期望副本数

# 1. 查看 Deployment 事件（<deployment-name> 和 <namespace> 替换为实际值）
kubectl describe deployment <deployment-name> -n <namespace>

# 2. 检查资源配额
kubectl describe quota -n <namespace>

# 3. 检查 LimitRange
kubectl describe limitrange -n <namespace>

# 4. 查看节点资源
kubectl describe nodes | grep -A 5 "Allocated resources"

四、Service 和网络故障排查

4.1 Service 状态检查

# 查看 Service 列表（<namespace> 替换为实际的命名空间名）
kubectl get services -n <namespace>

# 查看 Service 详情（<service-name> 和 <namespace> 替换为实际值）
kubectl describe service <service-name> -n <namespace>

# 查看 Endpoints
kubectl get endpoints <service-name> -n <namespace>
kubectl describe endpoints <service-name> -n <namespace>

4.2 Service 无法访问

# 1. 检查 Endpoints 是否为空（<service-name> 和 <namespace> 替换为实际值）
kubectl get endpoints <service-name> -n <namespace>

# 2. 检查 Pod 标签是否匹配
kubectl get pods --show-labels -n <namespace>
kubectl get service <service-name> -o jsonpath='{.spec.selector}' -n <namespace>

# 3. 测试 ClusterIP 连通性
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup <service-name>.<namespace>.svc.cluster.local

# 4. 从 Pod 内测试 Service
kubectl exec -it <pod-name> -n <namespace> -- curl <service-name>:<port>

4.3 Ingress 故障排查

# 查看 Ingress 列表（<namespace> 替换为实际的命名空间名）
kubectl get ingress -n <namespace>

# 查看 Ingress 详情（<ingress-name> 和 <namespace> 替换为实际值）
kubectl describe ingress <ingress-name> -n <namespace>

# 查看 Ingress Controller Pod
kubectl get pods -n ingress-nginx

# 查看 Ingress Controller 日志
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx

4.4 网络策略检查

# 查看 NetworkPolicy（<namespace> 替换为实际的命名空间名）
kubectl get networkpolicies -n <namespace>
kubectl describe networkpolicy <policy-name> -n <namespace>

# 测试 DNS 解析
kubectl run -it --rm dns-test --image=busybox:1.28 --restart=Never -- nslookup kubernetes.default

五、节点故障排查

5.1 节点状态检查

# 查看节点状态
kubectl get nodes

# 查看节点详情（<node-name> 替换为实际的节点名）
kubectl describe node <node-name>

# 查看节点条件
kubectl get node <node-name> -o jsonpath='{.status.conditions}'

# 查看节点资源使用
kubectl top node <node-name>

5.2 节点 NotReady 排查

# 1. 查看节点条件（<node-name> 替换为实际的节点名）
kubectl describe node <node-name> | grep -A 5 Conditions

# 2. 检查 kubelet 状态
systemctl status kubelet
journalctl -u kubelet -n 100

# 3. 检查节点磁盘
kubectl describe node <node-name> | grep -i disk

# 4. 检查节点内存
kubectl describe node <node-name> | grep -i memory

5.3 节点维护操作

# 标记节点不可调度（<node-name> 替换为实际的节点名）
kubectl cordon <node-name>

# 驱逐节点上的 Pod
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

# 恢复节点可调度
kubectl uncordon <node-name>

六、存储故障排查

6.1 PV/PVC 状态检查

# 查看 PersistentVolume
kubectl get pv

# 查看 PersistentVolumeClaim（<namespace> 替换为实际的命名空间名）
kubectl get pvc -n <namespace>

# 查看 StorageClass
kubectl get storageclass

# 查看 PVC 详情（<pvc-name> 和 <namespace> 替换为实际值）
kubectl describe pvc <pvc-name> -n <namespace>

6.2 PVC Pending 排查

# 1. 查看 PVC 事件（<pvc-name> 和 <namespace> 替换为实际值）
kubectl describe pvc <pvc-name> -n <namespace>

# 2. 检查 StorageClass
kubectl get storageclass
kubectl describe storageclass <storageclass-name>

# 3. 检查 PV 是否可用
kubectl get pv | grep Available

# 4. 检查存储类配置
kubectl get storageclass <storageclass-name> -o yaml

6.3 卷挂载失败

# 1. 查看 Pod 事件（<pod-name> 和 <namespace> 替换为实际值）
kubectl describe pod <pod-name> -n <namespace>

# 2. 检查节点插件
kubectl get csinode

# 3. 查看 CSI 驱动 Pod
kubectl get pods -n kube-system | grep csi

七、ConfigMap 和 Secret 排查

7.1 查看配置

# 查看 ConfigMap 列表（<namespace> 替换为实际的命名空间名）
kubectl get configmaps -n <namespace>

# 查看 ConfigMap 内容（<configmap-name> 和 <namespace> 替换为实际值）
kubectl get configmap <configmap-name> -o yaml -n <namespace>

# 查看 Secret 列表
kubectl get secrets -n <namespace>

# 查看 Secret 内容（base64 解码）
kubectl get secret <secret-name> -o jsonpath='{.data}' -n <namespace>
kubectl get secret <secret-name> -o jsonpath='{.data.username}' -n <namespace> | base64 -d

7.2 配置未生效排查

# 1. 检查 Pod 是否正确引用（<pod-name>、<configmap-name> 和 <namespace> 替换为实际值）
kubectl get pod <pod-name> -o yaml -n <namespace> | grep -A 5 configMapKeyRef

# 2. 检查卷挂载
kubectl get pod <pod-name> -o yaml -n <namespace> | grep -A 5 volumes

# 3. 进入容器验证
kubectl exec <pod-name> -n <namespace> -- env | grep <key>
kubectl exec <pod-name> -n <namespace> -- cat /etc/config/<file>

八、资源限制排查

8.1 OOMKilled 排查

# 1. 查看 Pod 退出原因（<pod-name> 和 <namespace> 替换为实际值）
kubectl get pod <pod-name> -o jsonpath='{.status.containerStatuses[0].lastState.terminated.reason}'

# 2. 查看资源使用
kubectl top pod <pod-name> -n <namespace>

# 3. 检查资源限制
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].resources}' -n <namespace>

# 4. 调整资源限制
kubectl set resources deployment/<deployment-name> -c <container-name> --limits=memory=512Mi -n <namespace>

8.2 CPU 限制排查

# 1. 查看 CPU 使用（<pod-name> 和 <namespace> 替换为实际值）
kubectl top pod <pod-name> -n <namespace>

# 2. 检查 CPU 节流
kubectl exec <pod-name> -n <namespace> -- cat /sys/fs/cgroup/cpu/cpu.stat

# 3. 调整 CPU 限制
kubectl set resources deployment/<deployment-name> -c <container-name> --limits=cpu=1 -n <namespace>

九、日志和监控

9.1 组件日志

# 查看 kubelet 日志
journalctl -u kubelet -n 100 --no-pager

# 查看 API Server 日志
kubectl logs -n kube-system -l component=kube-apiserver --tail=100

# 查看 Controller Manager 日志
kubectl logs -n kube-system -l component=kube-controller-manager --tail=100

# 查看 Scheduler 日志
kubectl logs -n kube-system -l component=kube-scheduler --tail=100

9.2 使用 kubectl debug

# 创建调试容器（<pod-name> 和 <namespace> 替换为实际值）
kubectl debug -it <pod-name> -n <namespace> --image=busybox

# 使用 ephemeral 容器调试
kubectl debug -it <pod-name> -n <namespace> --image=ubuntu --target=<container-name>

十、常用修复命令

10.1 Pod 修复

# 删除 Pod（让 Deployment 重建）（<pod-name> 和 <namespace> 替换为实际值）
kubectl delete pod <pod-name> -n <namespace>
kubectl delete pod -l app=<deployment-name> -n <namespace>

# 强制删除 terminating 状态的 Pod
kubectl delete pod <pod-name> -n <namespace> --grace-period=0 --force

10.2 配置修复

# 重新加载 ConfigMap
kubectl create configmap <configmap-name> --from-file=config.yaml --dry-run=client -o yaml | kubectl apply -f -

# 重新加载 Secret
kubectl create secret generic <secret-name> --from-literal=key=value --dry-run=client -o yaml | kubectl apply -f -

10.3 紧急处理

# 停止 Deployment 的自动恢复（<deployment-name> 和 <namespace> 替换为实际值）
kubectl scale deployment/<deployment-name> --replicas=0 -n <namespace>

# 恢复 Deployment
kubectl scale deployment/<deployment-name> --replicas=3 -n <namespace>

# 清理所有 Evicted Pod
kubectl get pods | grep Evicted | awk '{print $1}' | xargs kubectl delete pod

十一、故障排查流程图

11.1 Pod 故障排查流程

kubectl get pods -n <namespace>              # 查看 Pod 状态
kubectl describe pod <pod-name> -n <namespace>  # 查看事件和详情
# 根据状态码判断问题类型
kubectl logs <pod-name> -n <namespace>      # 查看应用日志
kubectl exec -it <pod-name> -n <namespace>  # 进入容器排查
# 修复配置或重新部署

11.2 故障分级

总结

本文整理了 Kubernetes 的完整故障排查命令：

• ✅ 集群状态检查（nodes、componentstatuses）
• ✅ Pod 故障排查（状态、日志、事件）
• ✅ Deployment 问题（rollout、回滚）
• ✅ Service 和网络故障（Endpoints、Ingress）
• ✅ 节点故障（NotReady、资源不足）
• ✅ 存储问题（PV、PVC、StorageClass）
• ✅ 资源限制（OOMKilled、CPU 节流）
• ✅ 日志和调试（组件日志、kubectl debug）

运维建议

1. 熟悉常用 kubectl 命令，快速定位问题
2. 配置完善的监控告警（Prometheus + Grafana）
3. 启用审计日志，追踪配置变更
4. 建立故障处理 SOP 和应急预案
5. 定期进行故障演练

🔗 相关链接

• Kubectl Cheat Sheet
• Kubernetes 调试指南
• Kubectl 参考文档

建议收藏本文，故障排查时快速查阅！有问题欢迎留言讨论！

cnbugsai

打赏 海报 链接