initializ/k8s-incident-triage

Kubernetes 事件故障排查

使用 kubectl 对 Kubernetes 工作负载和命名空间执行只读故障排查。

支持：

• 自然语言输入（人类模式）
• 结构化 JSON 输入（自动化模式）

该技能永远不会更改集群状态。

---

工具使用

此技能仅使用 cli_execute 执行 kubectl 命令。 切勿使用 http_request 或 web_search 与 Kubernetes 交互。 所有集群操作必须通过 cli_execute 工具使用 kubectl。

---

工具：k8s_triage

诊断不健康的 Kubernetes 工作负载、Pod 或命名空间。

---

输入模式

1) 人类模式（自然语言）

输入为纯文本字符串。

示例：

• triage payments-prod
• triage deployment payments-api in payments-prod
• why are pods pending in checkout-prod?
• investigate crashloop in payments-prod
• triage pod api-7c9f6d7f86-abcde in payments-prod
• check rollout of deployment payments-api in prod

行为：

• 解析命名空间、工作负载、Pod 或选择器意图。
• 如果未指定命名空间，则使用 $DEFAULT_NAMESPACE（如果已设置）。
• 如果存在歧义，则默认为命名空间级别的排查。
• 切勿要求用户记住 JSON 字段。

---

2) 自动化模式（结构化 JSON）

输入 JSON 模式：

{ "namespace": "payments-prod", "workload_kind": "deployment", "workload_name": "payments-api", "pod_name": null, "label_selector": null, "include_logs": true, "logs_tail_lines": 200, "include_previous_logs": true, "events_limit": 50, "include_node_diagnostics": true, "include_metrics": false, "output_format": "markdown" }

规则：

• namespace 为必填项。
• 如果提供了 pod_name → 进行 Pod 级别排查。
• 如果提供了工作负载字段 → 进行工作负载级别排查。
• 否则 → 进行命名空间扫描。

---

排查流程

步骤 0 — 前置条件

验证集群访问：

kubectl version --client kubectl cluster-info

如果 RBAC 拒绝访问：

• 继续执行允许的操作。
• 在输出中明确报告被拒绝的命令。

---

步骤 1 — 快速健康快照

命名空间范围：

kubectl get pods -n -o wide kubectl get deploy,sts,ds,job,cronjob -n

工作负载范围：

kubectl get -n kubectl rollout status / -n --timeout=10s

选择处于以下状态的 Pod：

• CrashLoopBackOff
• ImagePullBackOff
• ErrImagePull
• Pending / Unschedulable
• Error
• NotReady
• OOMKilled
• 高重启次数

将深度排查限制为 $TRIAGE_MAX_PODS（默认 5）。

---

步骤 2 — 事件时间线

kubectl get events -n --sort-by=.lastTimestamp | tail -n <events_limit>

查找：

• FailedScheduling
• FailedMount
• Unhealthy（探针失败）
• Back-off pulling image
• Evicted
• 节点压力信号

---

步骤 3 — 描述 Pod 和工作负载

对于每个选定的 Pod：

kubectl describe pod -n

捕获：

• 容器状态和原因
• 重启次数
• 上次终止原因
• 探针失败
• 卷挂载问题
• 节点分配
• 污点/容忍度
• 亲和性约束

如果是工作负载级别排查：

kubectl describe -n

---

步骤 4 — 节点诊断（可选）

kubectl get nodes -o wide kubectl describe node

检查：

• NotReady
• MemoryPressure
• DiskPressure
• PIDPressure
• 驱逐

---

步骤 5 — 日志（可选）

kubectl logs -n --all-containers --tail=

如果存在重启循环且 include_previous_logs=true：

kubectl logs -n --previous --all-containers --tail=

规则：

• 对于 CrashLoopBackOff，优先使用上一个日志。
• 编辑明显的敏感模式。
• 绝不打印 Secret 值。

---

步骤 6 — 可选指标

如果启用：

kubectl top pods -n kubectl top node

如果 metrics-server 不可用，则优雅跳过。

---

检测启发式规则

将检测到的问题分类为：

• CrashLoop / 应用程序崩溃
• OOMKilled / 资源限制
• 镜像拉取失败
• 调度约束
• 探针失败
• PVC / 卷故障
• 节点压力 / 驱逐
• Rollout 卡住
• 未知 / 需要升级处理

对于每个问题提供：

• 假设
• 支持证据
• 置信度分数（0.0–1.0）
• 推荐的下一步命令

---

输出结构

1) 事件摘要

• 命名空间
• 范围（Pod/工作负载/命名空间）
• 受影响资源数量
• 时间戳

2) 主要发现

简洁的要点总结。

3) 最可能的根因（前 3 个）

每个包含：

• 描述
• 证据摘录
• 置信度
• 推荐操作

4) 下一步命令

可复制粘贴的 kubectl 命令。

5) 证据附录

• 事件（最近）
• 描述摘录
• 日志摘录

---

安全约束

该技能必须：

• 仅执行只读的 kubectl 操作。
• 绝不执行：
  • apply
  • patch
  • delete
  • exec
  • port-forward
  • scale
  • rollout restart
• 绝不打印 Secret 值。
• 避免转储完整的环境变量。

---

自主兼容性

此技能设计用于被以下对象调用：

• k8s_alert_handler（告警触发排查）
• k8s_patrol（定期巡逻扫描）
• 通过自然语言 CLI 的人类

它必须：

• 保持幂等性
• 生成确定性指纹
• 避免过度的集群负载
• 限制深度排查范围