⚡

KubernetesDebuggingSkill k8s-debug

这是一个全面的 Kubernetes 调试和故障排除工具包。当您诊断 Kubernetes 集群问题、调试失败的 Pod、调查网络连接问题、分析资源使用、排查部署问题或执行集群健康检查时，请使用这项技能。

Docker/K8s 0 次安装 0 次浏览 更新于 3/4/2026

Kubernetes 调试技能

概览

系统化的工具包，用于调试和排查 Kubernetes 集群、Pod、服务和部署的问题。提供脚本、工作流程和参考指南，以高效识别和解决常见的 Kubernetes 问题。

何时使用此技能

遇到以下情况时调用此技能：

  • Pod 故障（CrashLoopBackOff、ImagePullBackOff、Pending、OOMKilled）
  • 服务连接或 DNS 解析问题
  • 网络策略或入口问题
  • 卷和存储挂载失败
  • 部署 rollout 问题
  • 集群健康或性能下降
  • 资源耗尽（CPU/内存）
  • 配置问题（ConfigMaps、Secrets、RBAC）

调试工作流程

按照这个系统化的方法来处理任何 Kubernetes 问题：

1. 确定问题层级

对问题进行分类：

  • 应用层：应用崩溃、错误、缺陷
  • Pod 层：Pod 无法启动、重启或挂起
  • 服务层：网络连接、DNS 问题
  • 节点层：节点未就绪、资源耗尽
  • 集群层：控制平面问题、API 问题
  • 存储层：卷挂载失败、PVC 问题
  • 配置层：ConfigMap、Secret、RBAC 问题

2. 收集诊断信息

根据范围使用适当的诊断脚本：

Pod 级别诊断

使用 scripts/pod_diagnostics.py 进行综合 Pod 分析：

python3 scripts/pod_diagnostics.py <pod-name> -n <namespace>

此脚本收集：

  • Pod 状态和描述
  • Pod 事件
  • 容器日志（当前和之前的）
  • 资源使用情况
  • 节点信息
  • YAML 配置

输出可以保存以供分析：python3 scripts/pod_diagnostics.py <pod-name> -n <namespace> -o diagnostics.txt

集群级健康检查

使用 scripts/cluster_health.sh 进行整体集群诊断：

./scripts/cluster_health.sh

此脚本检查：

  • 集群信息和版本
  • 节点状态和资源
  • 所有命名空间中的 Pods
  • 失败/挂起的 Pods
  • 最近的事件
  • 部署、服务、有状态副本集、守护进程集
  • PVC 和 PV
  • 组件健康
  • 常见错误状态（CrashLoopBackOff、ImagePullBackOff）

网络诊断

使用 scripts/network_debug.sh 进行连接问题：

./scripts/network_debug.sh <namespace> <pod-name>

此脚本分析：

  • Pod 网络配置
  • DNS 设置和解析
  • 服务端点
  • 网络策略
  • 连接测试
  • CoreDNS 日志

3. 遵循特定问题的流程

根据确定的问题，参考 references/troubleshooting_workflow.md 获取详细的工作流程：

  • Pod 挂起：资源/调度工作流程
  • CrashLoopBackOff：应用崩溃工作流程
  • ImagePullBackOff：拉取镜像工作流程
  • 服务问题：网络连接工作流程
  • DNS 故障：DNS 故障排除工作流程
  • 资源耗尽：性能调查工作流程
  • 存储问题：PVC 绑定工作流程
  • 部署卡住：Rollout 工作流程

4. 应用针对性修复

参考 references/common_issues.md 获取常见问题的特定解决方案。

常见调试模式

模式 1：Pod 无法启动

# 快速评估
kubectl get pod <pod-name> -n <namespace>
kubectl describe pod <pod-name> -n <namespace>

# 详细诊断
python3 scripts/pod_diagnostics.py <pod-name> -n <namespace>

# 检查常见原因：
# - ImagePullBackOff：验证镜像存在和凭证
# - CrashLoopBackOff：检查带有 --previous 标志的日志
# - Pending：检查节点资源和调度

模式 2：服务连接问题

# 验证服务和端点
kubectl get svc <service-name> -n <namespace>
kubectl get endpoints <service-name> -n <namespace>

# 网络诊断
./scripts/network_debug.sh <namespace> <pod-name>

# 从调试 Pod 测试连接
kubectl run tmp-shell --rm -i --tty --image nicolaka/netshoot -- /bin/bash
# 内部：curl <service-name>.<namespace>.svc.cluster.local:<port>

# 检查网络策略
kubectl get networkpolicies -n <namespace>

模式 3：应用性能问题

# 检查资源使用情况
kubectl top nodes
kubectl top pods -n <namespace> --containers

# 获取 Pod 指标
kubectl get pod <pod-name> -n <namespace> -o yaml | grep -A 10 resources

# 检查 OOMKilled
kubectl get pod <pod-name> -n <namespace> -o yaml | grep -A 10 lastState

# 查看应用日志
kubectl logs <pod-name> -n <namespace> --tail=100

模式 4：集群健康评估

# 运行综合健康检查
./scripts/cluster_health.sh > cluster-health-$(date +%Y%m%d-%H%M%S).txt

# 检查输出：
# - 节点条件和资源压力
# - 失败或挂起的 Pods
# - 最近的错误事件
# - 组件健康状态
# - 资源配额使用情况

基本手动命令

虽然脚本可以自动化诊断，但要理解这些核心命令：

Pod 调试

# 查看 Pod 状态
kubectl get pods -n <namespace> -o wide

# 详细 Pod 信息
kubectl describe pod <pod-name> -n <namespace>

# 查看日志
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous  # 之前的容器
kubectl logs <pod-name> -n <namespace> -c <container>  # 特定容器

# 在 Pod 中执行命令
kubectl exec <pod-name> -n <namespace> -it -- /bin/sh

# 获取 Pod YAML
kubectl get pod <pod-name> -n <namespace> -o yaml

服务和网络调试

# 检查服务
kubectl get svc -n <namespace>
kubectl describe svc <service-name> -n <namespace>

# 检查端点
kubectl get endpoints -n <namespace>

# 测试 DNS
kubectl exec <pod-name> -n <namespace> -- nslookup kubernetes.default

# 查看事件
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

资源监控

# 节点资源
kubectl top nodes
kubectl describe nodes

# Pod 资源
kubectl top pods -n <namespace>
kubectl top pod <pod-name> -n <namespace> --containers

紧急操作

# 重启部署
kubectl rollout restart deployment/<name> -n <namespace>

# 回滚部署
kubectl rollout undo deployment/<name> -n <namespace>

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

# 排空节点（维护）
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

# 限制节点（防止调度）
kubectl cordon <node-name>

参考文档

详细的故障排除指南

参考 references/troubleshooting_workflow.md 获取：

  • 每种问题类型的逐步工作流程
  • 诊断的决策树
  • 系统化调试的命令序列
  • 快速参考命令备忘单

常见问题数据库

参考 references/common_issues.md 获取：

  • 每个常见问题的详细解释
  • 症状和原因
  • 特定的调试步骤
  • 解决方案和修复
  • 预防策略

最佳实践

系统化方法

  1. 观察：在做出改变之前收集事实
  2. 分析：使用诊断脚本来收集全面的数据
  3. 假设：对根本原因形成理论
  4. 测试：用针对性的命令验证假设
  5. 修复：应用适当的解决方案
  6. 验证：确认问题已解决
  7. 记录：记录发现以供将来参考

数据收集

  • 将诊断输出保存到文件以供分析
  • 在重启失败的 Pods 之前捕获日志
  • 记录事件时间线以供事故报告
  • 导出资源指标以进行趋势分析

预防

  • 设置适当的资源请求和限制
  • 实施健康检查（liveness/readiness probes）
  • 使用适当的日志记录和监控
  • 逐步应用网络策略
  • 在非生产环境中测试更改
  • 维护集群架构的文档

高级调试技术

调试容器（Kubernetes 1.23+）

# 附加临时调试容器
kubectl debug <pod-name> -n <namespace> -it --image=nicolaka/netshoot

# 创建调试 Pod 的副本
kubectl debug <pod-name> -n <namespace> -it --copy-to=<debug-pod-name> --container=<container>

端口转发以进行测试

# 将 Pod 端口转发到本地机器
kubectl port-forward pod/<pod-name> -n <namespace> <local-port>:<pod-port>

# 转发服务端口
kubectl port-forward svc/<service-name> -n <namespace> <local-port>:<service-port>

代理 API 访问

# 启动 kubectl 代理
kubectl proxy --port=8080

# 访问 API
curl http://localhost:8080/api/v1/namespaces/<namespace>/pods/<pod-name>

自定义列输出

# 自定义 Pod 信息
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,IP:.status.podIP

# 节点污点
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

故障排除清单

在升级问题之前，请验证：

  • [ ] 查看 Pod 事件：kubectl describe pod
  • [ ] 查看 Pod 日志（当前和之前的）
  • [ ] 验证节点上的资源可用性
  • [ ] 确认镜像存在且可访问
  • [ ] 验证服务选择器与 Pod 标签匹配
  • [ ] 从 Pods 测试 DNS 解析
  • [ ] 检查网络策略
  • [ ] 查看最近的集群事件
  • [ ] 确认 ConfigMaps/Secrets 存在
  • [ ] 验证 RBAC 权限
  • [ ] 检查资源配额/限制
  • [ ] 查看集群组件健康状态

相关工具

Kubernetes 调试的其他有用工具：

  • kubectl-debug：高级调试插件
  • stern：多 Pod 日志跟踪
  • kubectx/kubens：上下文和命名空间切换
  • k9s：Kubernetes 的终端 UI
  • lens：Kubernetes 的桌面 IDE
  • Prometheus/Grafana：监控和报警
  • Jaeger/Zipkin：分布式跟踪