k8s-troubleshooter

Kubernetes 故障排查与事件响应

在生产环境中诊断和解决 Kubernetes 问题的系统化方法。

核心故障排查工作流

遇到任何 Kubernetes 问题时，请遵循以下系统化方法：

1. 收集背景信息

• 观察到的症状是什么？
• 问题何时开始？
• 最近有哪些变更（部署、配置、基础设施）？
• 影响范围是什么（单个 Pod、服务、节点、集群）？
• 对业务的影响是什么（严重级别）？

2. 初步分诊

运行集群健康检查：

# Check node status and health
kubectl get nodes

# Find non-running pods across all namespaces
kubectl get pods -A --field-selector status.phase!=Running

# Check node resource usage
kubectl top nodes

此检查会概述：

• 节点健康状态
• 所有命名空间中的待处理和失败 Pod
• 节点资源利用率

3. 深入调查

根据分诊结果，重点开展调查：

命名空间级问题：

python3 scripts/check_namespace.py <namespace>

此检查会全面评估命名空间健康状况：

• Pod 状态（运行中、待处理、失败、崩溃循环）
• 服务健康状况和端点
• 部署可用性
• PVC 状态
• 资源配额使用情况
• 最近的事件
• 可执行的建议

Pod 问题：

# Get full pod details (status, events, conditions, resource config)
kubectl describe pod <pod-name> -n <namespace>

# Check current and previous container logs
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous

# Get events specific to the pod
kubectl get events -n <namespace> --field-selector involvedObject.name=<pod-name>

此检查会显示：

• Pod 阶段和就绪状态
• 容器状态和运行状态
• 重启次数和退出代码
• 最近的事件和调度决策
• 资源请求和限制

其他调查：

• 检查所有命名空间的事件：kubectl get events -n <namespace> --sort-by='.lastTimestamp'

4. 确定根本原因

请查阅 references/common_issues.md，了解以下问题的详细信息：

• ImagePullBackOff / ErrImagePull
• CrashLoopBackOff
• 待处理的 Pod
• OOMKilled
• 节点问题（NotReady、DiskPressure）
• 网络故障
• 存储/PVC 问题
• 资源配额和限流
• RBAC 权限错误

每个问题都包含：

• 症状
• 常见原因
• 诊断命令
• 修复步骤
• 预防策略

5. 应用修复措施

根据已确定的根本原因，按照 common_issues.md 中的修复步骤进行处理。

务必：

• 尽可能先在非生产环境中测试修复措施
• 记录采取的操作
• 监控修复效果
• 准备好回滚计划

6. 验证与监控

应用修复后：

• 验证问题已解决
• 监控问题是否复发（至少 15-30 分钟）
• 检查相关系统
• 更新文档

事件响应

对于生产事件，请遵循 references/incident_response.md 中的结构化响应流程：

严重级别评估：

• SEV-1（严重）：服务完全中断、数据丢失、安全漏洞
• SEV-2（高）：严重降级、对用户造成重大影响
• SEV-3（中）：轻微受损，有可用的临时解决方案
• SEV-4（低）：外观问题、影响极小

事件阶段：

1. 检测 - 识别并评估
2. 分诊 - 确定范围和影响
3. 调查 - 查找根本原因
4. 解决 - 应用修复
5. 事件后处理 - 记录并改进

常见事件场景：

• 集群完全中断
• 服务降级
• 节点故障
• 存储问题
• 安全事件

详细操作手册请参阅 references/incident_response.md。

快速参考命令

集群概览

kubectl cluster-info
kubectl get nodes
kubectl get pods --all-namespaces | grep -v Running
kubectl get events --all-namespaces --sort-by='.lastTimestamp' | tail -20

Pod 诊断

kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --previous
kubectl exec -it <pod> -n <namespace> -- /bin/sh
kubectl get pod <pod> -n <namespace> -o yaml

节点诊断

kubectl describe node <node>
kubectl top nodes
kubectl top pods --all-namespaces
ssh <node> "systemctl status kubelet"
ssh <node> "journalctl -u kubelet -n 100"

服务与网络

kubectl describe svc <service> -n <namespace>
kubectl get endpoints <service> -n <namespace>
kubectl get networkpolicies --all-namespaces

存储

kubectl get pvc,pv --all-namespaces
kubectl describe pvc <pvc> -n <namespace>
kubectl get storageclass

资源与配置

kubectl describe resourcequota -n <namespace>
kubectl describe limitrange -n <namespace>
kubectl get rolebindings,clusterrolebindings -n <namespace>

诊断脚本

check_namespace.py

命名空间级健康检查与诊断：

• Pod 健康状况（运行中、待处理、失败、崩溃循环、镜像拉取错误）
• 服务健康状况和端点
• 部署可用性状态
• PersistentVolumeClaim 状态
• 资源配额使用情况和限制
• 最近的命名空间事件
• 健康状态评估
• 可执行的建议

用法：

# Human-readable output
python3 scripts/check_namespace.py <namespace>

# JSON output for automation
python3 scripts/check_namespace.py <namespace> --json

# Include more events
python3 scripts/check_namespace.py <namespace> --events 20

在排查特定命名空间的问题或评估整体命名空间健康状况时，此脚本最为适用。

集群级诊断（kubectl）

如需检查整个集群的健康状况，请直接使用 kubectl：

# Node health and status
kubectl get nodes
kubectl top nodes

# Find non-running pods across all namespaces
kubectl get pods -A --field-selector status.phase!=Running

# System pod health
kubectl get pods -n kube-system

Pod 级诊断（kubectl）

如需详细调查 Pod，请直接使用 kubectl：

# Full pod details (status, events, conditions, resource config)
kubectl describe pod <pod-name> -n <namespace>

# Current and previous container logs
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous

# Events specific to the pod
kubectl get events -n <namespace> --field-selector involvedObject.name=<pod-name>

参考文档

references/common_issues.md

Kubernetes 常见问题综合指南，包含：

• 详细的症状描述
• 根本原因分析
• 逐步诊断流程
• 修复说明
• 预防策略

涵盖：

• Pod 问题（ImagePullBackOff、CrashLoopBackOff、Pending、OOMKilled）
• 节点问题（NotReady、DiskPressure）
• 网络问题（Pod 间通信、服务访问）
• 存储问题（PVC Pending、卷挂载失败）
• 资源问题（配额超限、CPU 节流）
• 安全问题（漏洞、RBAC）

当你已确定具体问题类型，但需要详细的修复步骤时，请阅读本文档。

references/incident_response.md

结构化的事件响应框架，包含：

• 事件响应阶段（检测 → 分流 → 调查 → 解决 → 事后复盘）
• 严重级别定义
• 常见事件场景的详细操作手册
• 沟通指南
• 事后复盘模板
• 预防、准备、响应和恢复的最佳实践

响应生产环境事件或规划事件响应流程时，请阅读本文档。

references/performance_troubleshooting.md

全面的性能诊断与优化指南，涵盖：

• 高延迟问题 - API 响应时间、请求延迟排查
• CPU 性能 - 节流检测、性能分析、优化
• 内存性能 - OOM 问题、内存泄漏检测、堆分析
• 网络性能 - 延迟、丢包、DNS 解析
• 存储 I/O 性能 - 磁盘性能测试、优化
• 应用级指标 - Prometheus 集成、分布式追踪
• 集群级性能 - 控制平面、调度器、资源利用率

以下情况请阅读本文档：

• 调查应用响应缓慢的问题
• 诊断 CPU 或内存性能问题
• 排查网络延迟或连接问题
• 优化存储 I/O 性能
• 设置性能监控

references/helm_troubleshooting.md

Helm 故障排查完整指南，包含：

• 发布问题 - 发布卡住、资源缺失、状态问题
• 安装失败 - Chart 冲突、验证错误、模板渲染
• 升级与回滚 - 升级失败、不可变字段错误、回滚流程
• 值与配置 - 值未生效、解析错误、密钥处理
• Chart 依赖项 - 依赖项更新、版本冲突、子 Chart 值
• 钩子与生命周期 - 钩子失败、清理问题
• 仓库问题 - Chart 访问问题、版本不匹配

以下情况请阅读本文档：

• 使用 Helm 部署的应用
• 排查 Chart 安装或升级问题
• 调试 Helm 发布状态
• 管理 Chart 依赖项