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

擷取：

• 容器狀態與原因
• 重新啟動次數
• 上次終止原因
• 探針失敗
• 掛載磁碟區問題
• 節點指派
• Taints / tolerations
• 親和性限制

若為工作負載層級分類：

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 / 磁碟區故障
• 節點壓力 / 驅逐
• 部署卡住
• 未知 / 需要升級

針對每個問題提供：

• 假設
• 支援證據
• 信心分數（0.0–1.0）
• 建議的下一步指令

---

輸出結構

1) 事件摘要

• 命名空間
• 範圍（Pod / 工作負載 / 命名空間）
• 受影響資源數量
• 時間戳記

2) 主要發現

簡潔的項目符號摘要。

3) 可能根本原因（前 3 項）

每項包含：

• 描述
• 證據摘錄
• 信心
• 建議動作

4) 下一步指令

可直接複製貼上的 kubectl 命令。

5) 證據附錄

• 事件（近期）
• Describe 摘錄
• 日誌摘錄

---

安全限制

此技能必須：

• 僅執行唯讀的 kubectl 操作。
• 絕不執行：
  • apply
  • patch
  • delete
  • exec
  • port-forward
  • scale
  • rollout restart
• 絕不輸出 Secret 值。
• 避免傾印完整的環境變數。

---

自動化相容性

此技能設計為由以下項目呼叫：

• k8s_alert_handler（警示觸發的分類）
• k8s_patrol（排程巡邏掃描）
• 人類透過自然語言 CLI

它必須：

• 具備冪等性
• 產生確定性的指紋
• 避免過度的叢集負載
• 限制深度分類範圍