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

Kubernetes 5 小时前 0 1

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

一、快速诊断命令

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

# 查看特定命名空间的资源
kubectl get all -n 

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

1.3 事件查看

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

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

# 查看特定资源的事件
kubectl describe pod  -n 

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

1.4 故障定位流程

kubectl get nodes → 检查节点状态
kubectl get pods → 检查 Pod 状态
kubectl describe → 查看详细事件
kubectl logs → 查看容器日志
kubectl exec → 进入容器排查

二、Pod 故障排查

2.1 Pod 状态检查

# 查看 Pod 列表
kubectl get pods -n 

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

# 查看 Pod 的 YAML 配置
kubectl get pod  -o yaml -n 

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

2.2 Pod 状态说明

状态	说明	常见原因
`Pending`	等待调度	资源不足、节点选择器不匹配
`Running`	正在运行	正常状态
`Completed`	执行完成	Job 正常结束
`Failed`	执行失败	容器异常退出
`CrashLoopBackOff`	反复重启	应用启动失败、配置错误
`ImagePullBackOff`	镜像拉取失败	镜像不存在、认证失败
`ErrImagePull`	镜像拉取错误	镜像名称错误、网络问题
`ContainerCreating`	容器创建中	镜像拉取慢、存储挂载慢

2.3 Pod 无法启动排查

步骤 1：查看 Pod 详情

kubectl describe pod  -n 

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

步骤 2：查看容器日志

# 查看主容器日志
kubectl logs  -n 

# 查看指定容器日志（多容器 Pod）
kubectl logs  -c  -n 

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

# 实时查看日志
kubectl logs -f  -n 

# 查看最近 100 行日志
kubectl logs --tail=100  -n

步骤 3：进入容器排查

# 进入容器 shell
kubectl exec -it  -n  -- /bin/bash
kubectl exec -it  -n  -- /bin/sh

# 在容器中执行命令
kubectl exec  -n  -- ps aux
kubectl exec  -n  -- env

# 查看容器内文件系统
kubectl exec  -n  -- ls -la /app

2.4 CrashLoopBackOff 排查

# 1. 查看退出码
kubectl get pod  -o jsonpath='{.status.containerStatuses[0].lastState.terminated.exitCode}' -n 

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

# 3. 查看日志
kubectl logs  -p -n 

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

常见退出码：

0：正常退出
1：应用错误
137：OOMKilled（内存超限）
143：SIGTERM（优雅终止）

2.5 ImagePullBackOff 排查

# 1. 查看详细描述
kubectl describe pod  -n 

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

# 3. 手动拉取镜像测试
docker pull 

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

三、Deployment 故障排查

3.1 Deployment 状态检查

# 查看 Deployment 列表
kubectl get deployments -n 

# 查看 Deployment 详情
kubectl describe deployment  -n 

# 查看 ReplicaSet
kubectl get rs -n 

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

3.2 Deployment 无法更新

# 1. 查看 rollout 状态
kubectl rollout status deployment/ -n 

# 2. 查看 rollout 历史
kubectl rollout history deployment/ -n 

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

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

# 5. 暂停/继续 rollout
kubectl rollout pause deployment/ -n 
kubectl rollout resume deployment/ -n

3.3 Pod 无法达到期望副本数

# 1. 查看 Deployment 事件
kubectl describe deployment  -n 

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

# 3. 检查 LimitRange
kubectl describe limitrange -n 

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

四、Service 和网络故障排查

4.1 Service 状态检查

# 查看 Service 列表
kubectl get services -n 

# 查看 Service 详情
kubectl describe service  -n 

# 查看 Endpoints
kubectl get endpoints  -n 
kubectl describe endpoints  -n

4.2 Service 无法访问

# 1. 检查 Endpoints 是否为空
kubectl get endpoints  -n 

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

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

# 4. 从 Pod 内测试 Service
kubectl exec -it  -n  -- curl :

4.3 Ingress 故障排查

# 查看 Ingress 列表
kubectl get ingress -n 

# 查看 Ingress 详情
kubectl describe ingress  -n 

# 查看 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
kubectl get networkpolicies -n 
kubectl describe networkpolicy  -n 

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

五、节点故障排查

5.1 节点状态检查

# 查看节点状态
kubectl get nodes

# 查看节点详情
kubectl describe node 

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

# 查看节点资源使用
kubectl top node

5.2 节点 NotReady 排查

# 1. 查看节点条件
kubectl describe node  | grep -A 5 Conditions

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

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

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

5.3 节点维护操作

# 标记节点不可调度
kubectl cordon 

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

# 恢复节点可调度
kubectl uncordon

六、存储故障排查

6.1 PV/PVC 状态检查

# 查看 PersistentVolume
kubectl get pv

# 查看 PersistentVolumeClaim
kubectl get pvc -n 

# 查看 StorageClass
kubectl get storageclass

# 查看 PVC 详情
kubectl describe pvc  -n

6.2 PVC Pending 排查

# 1. 查看 PVC 事件
kubectl describe pvc  -n 

# 2. 检查 StorageClass
kubectl get storageclass
kubectl describe storageclass 

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

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

6.3 卷挂载失败

# 1. 查看 Pod 事件
kubectl describe pod  -n 

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

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

七、ConfigMap 和 Secret 排查

7.1 查看配置

# 查看 ConfigMap 列表
kubectl get configmaps -n 

# 查看 ConfigMap 内容
kubectl get configmap  -o yaml -n 

# 查看 Secret 列表
kubectl get secrets -n 

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

7.2 配置未生效排查

# 1. 检查 Pod 是否正确引用
kubectl get pod  -o yaml -n  | grep -A 5 configMapKeyRef

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

# 3. 进入容器验证
kubectl exec  -n  -- env | grep 
kubectl exec  -n  -- cat /etc/config/

八、资源限制排查

8.1 OOMKilled 排查

# 1. 查看 Pod 退出原因
kubectl get pod  -o jsonpath='{.status.containerStatuses[0].lastState.terminated.reason}'

# 2. 查看资源使用
kubectl top pod  -n 

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

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

8.2 CPU 限制排查

# 1. 查看 CPU 使用
kubectl top pod  -n 

# 2. 检查 CPU 节流
kubectl exec  -n  -- cat /sys/fs/cgroup/cpu/cpu.stat

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

九、日志和监控

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

# 创建调试容器
kubectl debug -it  -n  --image=busybox

# 使用 ephemeral 容器调试
kubectl debug -it  -n  --image=ubuntu --target=

十、常用修复命令

10.1 Pod 修复

# 删除 Pod（让 Deployment 重建）
kubectl delete pod  -n 
kubectl delete pod -l app= -n 

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

10.2 配置修复

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

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

10.3 紧急处理

# 停止 Deployment 的自动恢复
kubectl scale deployment/ --replicas=0 -n 

# 恢复 Deployment
kubectl scale deployment/ --replicas=3 -n 

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

十一、故障排查流程图

11.1 Pod 故障排查流程

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

11.2 故障分级

级别	现象	响应时间	示例
P0	集群不可用	立即	API Server 宕机、etcd 故障
P1	服务中断	30 分钟内	核心应用 Pod 全部失败
P2	部分功能异常	2 小时内	单 Pod 故障、性能下降
P3	轻微问题	计划内	配置优化、资源调整

总结

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

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

运维建议：

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

🔗 相关链接

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

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。