k8s-debug

Kubernetes 调试技能

概述

一套系统化工具包，采用确定性、安全优先的工作流，用于调试 Kubernetes 集群、工作负载、网络和存储。

触发短语

当请求类似以下内容时，使用此技能：

• “我的 Pod 处于 CrashLoopBackOff 状态；帮我找出根本原因。”
• “一个 Pod 中的 Service DNS 正常，但另一个 Pod 中不正常。”
• “Deployment 的滚动更新卡住了。”
• “Pod 处于 Pending 状态，无法调度。”
• “变更后集群健康状况似乎有所下降。”
• “PVC 一直处于等待状态，Pod 无法挂载存储。”

前提条件

请在技能目录（devops-skills-plugin/skills/k8s-debug）中运行，以便相对脚本路径能按原样使用。

必需

• 已安装并配置 kubectl。
• 有效的集群上下文。
• 对命名空间、Pod、事件、Service 和节点具有读取权限。

快速预检：

kubectl config current-context
kubectl auth can-i get pods -A
kubectl auth can-i get events -A
kubectl get ns

可选但建议

• 使用 jq 在 ./scripts/cluster_health.sh 中进行更精准的筛选。
• 用于 kubectl top 的 Metrics API（metrics-server）。
• 容器内调试工具（nslookup、getent、curl、wget、ip），用于深入网络测试。

回退行为：

• 如果缺少可选工具，脚本仍会继续运行，并在输出内容减少的同时打印警告。
• 如果 kubectl top 不可用，请继续使用 kubectl describe 和事件进行排查。

何时使用此技能

以下情况可使用此技能：

• Pod 故障（CrashLoopBackOff、ImagePullBackOff、Pending、OOMKilled）
• Service 连通性或 DNS 解析问题
• 网络策略或 Ingress 问题
• 卷和存储挂载失败
• Deployment 滚动更新问题
• 集群健康状况或性能下降
• 资源耗尽（CPU/内存）
• 配置问题（ConfigMaps、Secrets、RBAC）

破坏性命令的安全规则

默认先进行只读诊断。只有在确认影响范围和回滚方案后，才执行破坏性命令。

需要明确确认的命令：

• kubectl delete pod ... --force --grace-period=0
• kubectl drain ...
• kubectl rollout restart ...
• kubectl rollout undo ...
• kubectl debug ... --copy-to=...

执行破坏性操作前：

# Snapshot current state for rollback and incident notes
kubectl get deploy,rs,pod,svc -n <namespace> -o wide
kubectl get pod <pod-name> -n <namespace> -o yaml > before-<pod-name>.yaml
kubectl get events -n <namespace> --sort-by='.lastTimestamp' > before-events.txt

参考导航图

只加载与已观察到的症状相关的部分。

症状 / 需求	打开	起始章节
需要端到端的诊断路径	./references/troubleshooting_workflow.md	General Debugging Workflow
Pod 状态为 Pending、CrashLoopBackOff 或 ImagePullBackOff	./references/troubleshooting_workflow.md	Pod Lifecycle Troubleshooting
Service 无法访问或 DNS 故障	./references/troubleshooting_workflow.md	Network Troubleshooting Workflow
节点压力或性能回退	./references/troubleshooting_workflow.md	Resource and Performance Workflow
PVC / PV / 存储类问题	./references/troubleshooting_workflow.md	Storage Troubleshooting Workflow
快速按症状查找解决方案	./references/common_issues.md	对应的问题标题
已知问题的事后修复方案	./references/common_issues.md	Solutions 章节

脚本概览

脚本	用途	必需参数	可选参数	输出	回退行为
./scripts/cluster_health.sh	集群范围的健康快照（节点、工作负载、事件、常见故障状态）	无	--strict、K8S_REQUEST_TIMEOUT 环境变量	将分节报告输出到 stdout	检查失败时继续执行，并在摘要和退出代码中记录失败
./scripts/network_debug.sh	以 Pod 为中心的网络和 DNS 诊断	<pod-name>（<namespace> 默认为 default）	--strict、--insecure、K8S_REQUEST_TIMEOUT 环境变量	将分节报告输出到 stdout	默认使用安全 API 探测；只有显式指定 --insecure 才会使用不安全 TLS
./scripts/pod_diagnostics.py	深入诊断 Pod（状态、描述、YAML、事件、各容器日志、节点上下文）	<pod-name>	-n/--namespace、-o/--output	将分节报告输出到 stdout 或文件	缺少访问权限时快速失败；跳过可选的指标/日志部分时会显示清晰提示

脚本退出代码

./scripts/cluster_health.sh 和 ./scripts/network_debug.sh 遵循相同的约定：

• 0：检查已完成且没有检查失败（除非设置了 --strict，否则允许出现警告）。
• 1：一项或多项检查失败，或在 --strict 模式下出现警告。
• 2：前置条件受阻（例如：缺少 kubectl、没有活动上下文、无法访问命名空间/Pod）。

确定性调试工作流

针对任何 Kubernetes 问题，请遵循以下系统化方法：

1. 预检和范围

kubectl config current-context
kubectl get ns
kubectl auth can-i get pods -n <namespace>

如果预检失败，请停止操作，先修复访问权限/上下文问题。

2. 确定问题所在层级

对问题进行分类：

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

3. 使用合适的脚本收集诊断信息

根据问题范围使用相应的诊断脚本：

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 > cluster-health-$(date +%Y%m%d-%H%M%S).txt

此脚本会检查：

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

网络诊断

使用 ./scripts/network_debug.sh 诊断连接问题：

./scripts/network_debug.sh <namespace> <pod-name>
# or force warning sensitivity / insecure TLS only when explicitly needed:
./scripts/network_debug.sh --strict <namespace> <pod-name>
./scripts/network_debug.sh --insecure <namespace> <pod-name>

此脚本会分析：

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

4. 遵循针对特定问题的参考工作流

根据已识别的问题，查阅 ./references/troubleshooting_workflow.md：

• Pod 处于等待状态：资源/调度工作流
• CrashLoopBackOff：应用崩溃工作流
• ImagePullBackOff：镜像拉取工作流
• 服务问题：网络连接工作流
• DNS 故障：DNS 故障排查工作流
• 资源耗尽：性能调查工作流
• 存储问题：PVC 绑定工作流
• 部署卡住：滚动发布工作流

5. 应用针对性修复

请参阅 ./references/common_issues.md，根据具体症状进行修复。

6. 验证并结束

运行最终验证：

kubectl get pods -n <namespace> -o wide
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | tail -20
kubectl rollout status deployment/<name> -n <namespace>

当用户可见的行为恢复正常，且没有新的严重警告事件出现时，问题即已解决。

示例流程

示例 1：payments 命名空间中的 CrashLoopBackOff

python3 ./scripts/pod_diagnostics.py payments-api-7c97f95dfb-q9l7k -n payments -o payments-diagnostics.txt
kubectl logs payments-api-7c97f95dfb-q9l7k -n payments --previous --tail=100
kubectl get deploy payments-api -n payments -o yaml | grep -A 8 livenessProbe

然后打开 ./references/common_issues.md，并应用 CrashLoopBackOff 解决方案。

示例 2：服务 DNS／连接故障

./scripts/network_debug.sh checkout checkout-api-75f49c9d8f-z6qtm
kubectl get svc checkout-api -n checkout
kubectl get endpoints checkout-api -n checkout
kubectl get networkpolicies -n checkout

然后按照 ./references/troubleshooting_workflow.md 中的 Service Connectivity Workflow 操作。

必备手动命令

Pod 调试

# View pod status
kubectl get pods -n <namespace> -o wide

# Detailed pod information
kubectl describe pod <pod-name> -n <namespace>

# View logs
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous  # Previous container
kubectl logs <pod-name> -n <namespace> -c <container>  # Specific container

# Execute commands in pod
kubectl exec <pod-name> -n <namespace> -it -- /bin/sh

# Get pod YAML
kubectl get pod <pod-name> -n <namespace> -o yaml

服务和网络调试

# Check services
kubectl get svc -n <namespace>
kubectl describe svc <service-name> -n <namespace>

# Check endpoints
kubectl get endpoints -n <namespace>

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

# View events
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

资源监控

# Node resources
kubectl top nodes
kubectl describe nodes

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

紧急操作

# Restart deployment
kubectl rollout restart deployment/<name> -n <namespace>

# Rollback deployment
kubectl rollout undo deployment/<name> -n <namespace>

# Force delete stuck pod
kubectl delete pod <pod-name> -n <namespace> --force --grace-period=0

# Drain node (maintenance)
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

# Cordon node (prevent scheduling)
kubectl cordon <node-name>

完成标准

满足以下所有条件时，故障排查会话即告完成：

• 已确认集群上下文和命名空间。
• 已记录相关诊断脚本的输出。
• 已找到根本原因，并将其与证据（事件／日志／配置／状态）关联。
• 执行任何有影响的操作前，已创建快照并制定回滚计划。
• 修复验证命令显示状态正常。
• 已在备注中记录使用的参考路径（./references/troubleshooting_workflow.md 或 ./references/common_issues.md）。

相关工具

用于 Kubernetes 调试的实用工具：

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