kube-verdict

# KubeVerdict 适用于企业的、轻量级LLM、GitOps法医层，用于Kubernetes事件。 KubeVerdict使用**anchor-by-render**：它从Helm/GitOps渲染的清单中重建预期状态，将其与Kubernetes实时状态进行比较，并将差异转化为一级RCA证据，然后进行LLM解释或人工批准的补救。 ✅ 默认情况下与外部隔离 — Ollama + Mistral，无数据离开您的基础设施 ✅ 无明确批准不自动修复 ✅ 十种故障场景在CI中端到端复制为离线fixtures ✅ 无需实时集群即可试用 [](https://github.com/a1h8/kube-verdict/actions/workflows/ci.yml) [](#验证场景) [](https://www.python.org) [](LICENSE) --- ## 为什么它很重要 大多数Kubernetes停机并非由单个Pod故障引起。 当支付服务崩溃时，值班工程师同时打开五个标签页：Pod日志、Kubernetes事件、Helm历史、Prometheus图表和GitOps仓库。在压力下，凌晨2点，还有三个Slack线程打开。根本原因很少在警报触发的地方——它通常在三个跳转之外，位于配置错误的Helm值或声明的内容与实际运行的内容之间的差异。 KubeVerdict减少了这种认知负担。它从Alertmanager事件信号开始，将Kubernetes事件和Helm/GitOps差异与从源渲染的预期状态相关联，因此RCA从意图开始，而不仅仅是从实时症状开始——然后根据置信度对诊断进行排名，并在任何补救命令触及生产之前设置人为审批门槛。 --- ## Anchor-by-render 大多数Kubernetes RCA工具从实时症状开始：事件、日志、指标和警报。 KubeVerdict提前一步：它从Helm/GitOps渲染的清单中重建应该运行的内容。 此渲染的预期状态成为证据锚点。然后，KubeVerdict将其与实时集群状态进行比较，检测声明与观察到的差异，并使用该差异对根本原因假设进行排名。 LLM不会编造诊断。它解释从渲染意图、运行时状态、Kubernetes事件、策略信号、时间异常和事件内存构建的证据路径。 > 状态：当前的验证场景集锻炼Helm-values-drift路径。应该在声明全渲染验证之前将更强大的GitOps渲染与实时场景提升到验证的h0NN集中。 > ArgoCD检测到漂移以决定是否协调。KubeVerdict使用相同的差异作为RCA证据——不是作为同步触发器。 --- ## 企业锚点，而非通用RCA KubeVerdict不要求LLM猜测根本原因。它构建**类型化证据锚点** — 探针、资源、镜像、服务、依赖项、策略、所有者、版本、图表值 — 从确定性源，排名RCA假设，然后仅使用LLM **解释排名裁决**。 它可以绘制的证据源，以及目前证明的程度： | 证据源 | 状态 | |---|---| | Helm值漂移（声明 vs 实时） | **验证** （h001–h010） | | Kubernetes事件 / 运行时状态 | **验证** | | 已解决事件内存（过去的人工批准修复） | **连接并填充** — `knowledge/example_store.py`，`data/examples`中的221个示例，索引到FAISS | | 策略报告（Kyverno / OPA `PolicyReport`） | **连接** — 作为`PolicyViolation`证据被摄入 | | 渲染Helm/GitOps清单（预期状态） | **可选** — 使用`GITOPS_REPO_URL`激活 | | 企业文档 / 运行手册 / SOP | **可插拔** — `knowledge/doc_indexer.py`索引`EnterpriseDoc`块；默认情况下不传输语料库 | 由于诊断是在模型运行之前从确定性锚点组装的， KubeVerdict是 **LLM-light**：幻觉较少，可重复性更高，可审计的证据路径 — 平台或SRE团队在信任和批准补救之前需要的属性。 --- ## 无需集群即可试用 **集成测试**选项卡完全离线运行 — 无需集群，无需Ollama： 1. `streamlit run ui/app.py` 2. 进入 **🧪 集成测试** 3. 从下拉菜单中选择任何`h00N_*`案例 4. 模式默认为 **🔬 管道跟踪** — 管道自动运行 5. 探索所有10个步骤：tokenizer → 检索 → 锚点 → 漂移 → 置信度 → 提出的修复 --- ## 演示 ### 浏览器UI — 无需集群  ```bash bash demo/kap_record_ui.sh # 启动Streamlit，打开浏览器 ``` --- ### CLI — 实时k3d集群，端到端循环  实时集群上的完整循环：Alertmanager警报 → 7秒内RCA → 人工审批 → 集群恢复。 ``` Alertmanager触发KubePodCrashLooping ↓ 202 接受，会话创建 KubeVerdict摄入实时Kubernetes事件 ↓ 7秒 根本原因： "dial tcp db-primary:5432: 连接被拒绝 — 数据库初始化失败" 置信度： 中等 · 影响范围： 5个资源 ↓ 人工门槛 是否批准补救？ [y/N] → y ↓ db-primary部署 · payment-service重新连接 · analytics-worker恢复 所有Pod正在运行 ✓ ``` ```bash bash demo/kap_record.sh # 重置 → 基线 → 启动API bash demo/cluster_setup.sh --inject python demo/demo_webhook.py # 警报 → RCA → 批准 → 修复 ``` --- ### 决策过程 — 阈值、死胡同和人工门槛 一个78秒的决策引擎实战演示：一个严格的阈值拒绝低置信度路径，KubeVerdict回溯，一个宽容的配置文件找到有效的补救措施，执行在人工门槛处停止。 ▶ [观看决策过程（78秒，MP4）](demo-decision-thresholds.mp4) · 字幕已烧录 → [完整演示指南](docs/demo.md) --- ## 安全模型 每个补救命令在执行前都经过两个门槛： 1. **人工审批** — SRE审查证据、根本原因和提出的修复方案，然后再应用任何更改 2. **回滚计划** — KubeVerdict生成每个修复提案的逆向命令（`helm rollback`、`kubectl rollout undo`） 每个提案都附带一个**影响范围估计**（低 / 中 / 高 / 关键）。目前，这是一个启发式方法，基于**拟议命令** — 它解析kubectl/helm动词、命名空间、资源类型、集群范围和受影响的资源数量。它 **不是** 资源的渲染与实时差异；将其视为分诊信号，而不是影响保证。 在明确批准之前，集群中没有任何操作。设计上不实现自主执行。 --- ## 工作原理 LLM受到检索证据的约束。KubeVerdict首先从确定性信号排名假设 — 本体拓扑、锚点违规、漂移、策略和已解决的事件 — 然后仅使用LLM生成基于证据的RCA。 **证据组装** — 运行时和企业输入馈送相同的图： ``` RUNTIME（实时集群） 企业上下文 ─────────────────────── ─────────────────────────────────────── Kubernetes状态 / 事件 企业Helm图表 ─► 渲染的清单 （可选） 日志 / 指标 企业文档 / 运行手册 / SOP （可插拔） Kyverno / OPA策略报告 （已连接） 已解决事件内存 （已填充） │ │ └───────────────► 合并到 ◄────────────┘ │ 声明与观察到的漂移 + 类型证据锚点 │ 实体图 （类型实体 + 关系） │ BM25 + FAISS + RRF混合检索 │ 基于证据的假设排名 ``` **然后是一个决策引擎 — 不是一-shot RCA。** 排名假设输入LangGraph状态 机器人在两个阶段运行，由一个条件边连接： ``` 分析 ⟲ 置信度路由器 → 收敛 → 影响范围 · 蒙特卡罗 · 策略裁决 → 人工门槛 ⟲ ``` 两个连续的低结果存档路径并重新排名剩余的候选（梁搜索）。在 收敛时，解决方案被门控 — 影响范围估计 → 蒙特卡罗稳定性 → 策略裁决 （**自动 / 人工审查 / 不允许**）。生产环境始终路由到人工门槛（当前：突破玻璃 · 目标：PR/MR优先）；门槛是LangGraph中断，因此操作员可以批准、拒绝或 注入额外的上下文以重新运行分析。已批准的修复被记住并 shortcut 相同的未来事件。 → [完整的两阶段节点/边图](docs/architecture.md#two-phase-decision-graph). --- ## 验证场景 十种故障模式在CI中端到端复制为离线fixtures — 无需集群，无需Ollama。 | 场景 | 案例 | 证明内容 | |---|---|---| | CrashLoopBackOff — 缺失依赖 | h001 | BFS图遍历，BM25+FAISS检索，锚点检测，置信度评分，修复提案 | | ImagePullBackOff — 注册表认证 / 标签漂移 | h002 | Helm漂移检测，`drift.*`注解，镜像提案生成 | | OOMKilled — 内存限制漂移 | h003 | Helm声明与观察到的差异，`anchor_fix_hints()` → `helm upgrade --set` | | 丢失的ConfigMap / Secret在Pod启动时 | h004 | `DeploymentReadinessDetector`，`missing.*`注解，`kubectl create`提示 | | RBAC — 缺失ClusterRoleBinding | h005 | SA存在但未检测到绑定，`kubectl create clusterrolebinding`提示 | | NetworkPolicy出口阻塞 | h006 | `netpol.*`注解，`kubectl edit networkpolicy`提示 | | HPA无法缩放 — metrics-server不可用 | h007 | HPA目标解析，metrics-server不可用检测，`metrics-server`修复提示 | | Init容器失败 — DB迁移退出1 | h008 | `Init:0/1`检测，init-container日志关联，根原因迁移失败 | | Liveness探测过于激进 — 杀死健康Pod | h009 | 探测超时漂移（`timeoutSeconds`声明与部署）→ `helm upgrade`修复 | | ResourceQuota超过 — Pod卡在Pending状态 | h010 | `ResourceQuota`实体，命名空间配额关联，Pod根原因 | | GitOps渲染与实时漂移 — OOMKilled（fixture） | h012 | `helm template`预期状态与实时集群差异（副本3→1，内存512Mi→128Mi）；`oom_kill`排名H1 | 案例h001–h010每个都有一个`test_hybrid_pipeline_NNN.py`运行完整的LLM前管道：图构造 → 混合检索（BM25 + FAISS + RRF）→ 上下文构建 → 锚点/漂移/策略评分 → 提案生成。另一个案例 — **h011（StatefulSet更新卡在绑定PVC上）** — 已连接但尚未通过其置信度/可解路径断言；它是一个很好的第一个贡献。 **h012**（`test_render_vs_live_h012.py`）验证 **anchor-by-render**路径：预期状态通过`helm template`渲染（作为证据提交）并与观察到的集群进行差异。差异/排名在CI中确定性运行，无需**helm二进制**；helm守护检查重新渲染图表以保持提交的黄金信仰。它是一个 **fixture-based**场景 — 它演示渲染与实时证据流，而不是生产级遥测。 --- ## 快速入门 **前提条件：** Python 3.11+，可通过kubeconfig访问的Kubernetes集群，以及在`.env`中配置的LLM提供程序。 **Kubernetes版本：** KubeVerdict是**版本感知**的 — 它在启动时检测API服务器版本，并适应API选择（Ingress，CronJob，HPA，PodSecurityPolicy）跨Kubernetes **1.19 → 当前**，并解析k3s/k3d版本字符串（`v1.28.3+k3s1`）。参见 [多版本Kubernetes](docs/architecture.md#multi-version-kubernetes). ```bash git clone https://github.com/a1h8/kube-verdict.git cd kube-verdict pip install -r requirements.txt cp .env.example .env # 编辑.env：KUBECONFIG，LLM_PROVIDER，KUBE_NAMESPACES # LLM_PROVIDER=ollama → ollama pull mistral （本地，无数据离开基础设施） # LLM_PROVIDER=groq → 设置GROQ_API_KEY （快速，免费层） # LLM_PROVIDER=anthropic|openai|google → 设置相应的API密钥 streamlit run ui/app.py ``` --- ## 接口 相同的调查可以通过多个界面访问： - **REST API（FastAPI）** — Docker镜像中附带的运行时（`uvicorn api.app:app --port 8000`）。会话生命周期在 `/api/v1/sessions` 下， 一次调用 `POST /api/v1/investigate` 返回一个稳定的判决信封（根本原因，置信度，影响范围，策略裁决，补救）。可选的共享密钥承载保护通过 `KUBEVERDICT_API_TOKEN`（不是OIDC）。参见 [REST API](docs/api.md). - **Streamlit演示** — `streamlit run ui/app.py`；上述离线管道跟踪器。 - **决策旅程（React仪表盘）** — `npm --prefix dashboard run dev`，然后打开`…/#/journey`。从API渲染 **决策过程**：判决，探索/消除假设路径和决策时间线。点击 **加载样本** 以查看完整的旅程，无需集群或Ollama。 - **MCP / 代理技能** — `kube_rca`，`helm_drift`，`expected_state_drift`，`blast_radius`（见下文）。 --- ## 文档 | 文档 | 内容 | |---|---| | [Anchor-by-render](docs/anchor-by-render.md) | 核心概念：渲染Helm/GitOps意图作为证据锚点，为什么不是ArgoCD，诚实状态 | | [架构](docs/architecture.md) | 完整的管道图，LangGraph工作流，基于证据的假设生成，锚点系统设计，漂移检测 | | [REST API](docs/api.md) | FastAPI端点，会话生命周期，请求/响应示例，SSE流 | | [UI参考](docs/ui.md) | Streamlit选项卡，管道跟踪步骤，锚点透视表，推理旅程，路由器决策 | | [测试用例](docs/test-cases.md) | h001–h010验证场景，案例格式，添加新案例，CI覆盖率 | | [项目布局](docs/project-layout.md) | 完整的目录树，RBAC | | [路线图](docs/roadmap.md) | 已完成和下一步 | | [配置](docs/configuration.md) | 所有`.env`变量，混合检索调谐，源权重 | | [部署](docs/deployment.md) | Docker，k3d，生产K8s | --- ## 代理技能 / MCP集成 KubeVerdict将`kube_rca`，`helm_drift`，`expected_state_drift`和`blast_radius`公开为MCP工具，可供任何MCP兼容的客户端（Claude Desktop，Cursor，Continue）使用。`expected_state_drift`与部署模式无关 — 它在固定的版本差异对实时集群进行差异化。 ### Claude Desktop ```json { "mcpServers": { "kube-verdict": { "command": "python", "args": ["mcp_server.py"], "cwd": "/path/to/kube-verdict" } } } ``` ### Cursor 添加 `.cursor/mcp.json`到您的项目根目录： ```json { "mcpServers": { "kube-verdict": { "command": "python", "args": ["mcp_server.py"], "cwd": "/path/to/kube-verdict" } } } ``` ### 空气隔离集群 所有三个工具完全离线运行 — Ollama + Mistral，无数据离开您的基础设施： ```bash ollama serve & # 本地LLM在端口11434 python mcp_server.py # MCP标准输入/输出服务器，从env读取kubeconfig ``` **嵌入模型：** 容器镜像不包含`all-MiniLM-L6-v2` sentence-transformer（~90 MB） — 它在首次使用时被检索。为了密封 的空气隔离部署，在连接的机器上先预先启动，然后将缓存放入容器 `/app/.cache/huggingface`: ```bash # 在连接的机器上 — 人口填充 ~/.cache/huggingface python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')" # 然后将该目录挂载到容器 `/app/.cache/huggingface`（k8s：PVC或hostPath卷） # 参见 [SKILL.md](SKILL.md) 完整的工具引用和空气隔离RBAC设置。 ### OpenAI兼容的模式 工具模式也以OpenAI函数调用格式在 [`openapi_tools.json`](openapi_tools.json)中可用， 与任何支持函数调用的SDK兼容（OpenAI，LangChain，LlamaIndex）。 它从MCP工具定义生成 — 使用与MCP服务器相同的处理程序： ```bash python tools/gen_openapi_tools.py # 重写openapi_tools.json python tools/gen_openapi_tools.py --check # CI守护：失败如果过时 ``` 将`openapi_tools.json`作为`tools`数组提供给任何函数调用LLM，然后 执行模型的工具调用与MCP服务器使用的相同处理程序： ```python from mcp_server import dispatch_openai_tool_calls for call.call(model_dump()) messages.append(tool_message) # role=tool, ready for the next turn ``` ## 时间证据（PatchTST） KubeVerdict 将 PatchTST视为**支持时间证据层，而不是根本原因引擎。它不预测事件。** 时间检测器（`signals/patchtst_detector.py`）可以产生预测残差、重建误差、z-score 回退和状态转换信号。这些信号**增强或减弱**已经基于 GitOps 意图、渲染的 manifest、Kubernetes 运行证据、策略违规和事件记忆的 RCA 假设。 **状态 — 实验性。** 当 Prometheus 不存在时，分析器会回退到合成的/基于 fixture 的历史记录，而短信号会回退到 z-score。这些场景说明了证据流；**它们不是生产级别的事件预测**，直到连接并验证真正的 Prometheus 支持的遥测数据时。请将时间异常分数视为支持信号，而不是验证的证据。 > 可以理解为 *"PatchTST 提供时间证据，加强或减弱 KubeVerdict RCA 假设"* — **而不是** *"KubeVerdict 使用 PatchTST 预测事件。"* **来源。** PatchTST 模型通过 HuggingFace [`transformers`](https://github.com/huggingface/transformers) 实现 *"A Time Series is Worth 64 Words: Long-term Forecasting with Transformers"*（Nie et al., ICLR 2023）— 原始实现：[yuqinie98/PatchTST](https://github.com/yuqinie98/PatchTST)（Apache-2.0）。KubeVerdict 不提供 PatchTST 源代码；`signals/patchtst_detector.py` 是基于库模型的原始检测器。一个配套操作分支 — [a1h8/PatchTST](https://github.com/a1h8/PatchTST) — 将 PatchTST 适配为 KubeVerdict 的时间证据管道。 --- ## 当前限制 有几个约束是故意的或已知的： - **已验证案例：h001–h010**（h011 已连接但尚未通过 — 参见已验证场景）。高级场景正在规划中 — Helmfile 多版本发布、MCTS 路由、Slack/PagerDuty 增强、RBAC 感知（模拟）范围 — 尚未实现。 - **单集群。** 集群间支持尚未完全连接。 - **生产环境中没有自动修复。** 人工审批环节是设计如此；自动执行尚未实现。 - **LLM 性能依赖于本地硬件。** 通过 Ollama 的 Mistral 需要至少 8 GB RAM；GPU 可以显著加速推理。 - **主要验证输入：Kubernetes 事件和 Helm 漂移。** Prometheus、Loki 和 OTel 收集器存在且已连接，但 E2E 演示和验证测试案例目前关注 K8s 事件 + Helm 漂移路径。 - **时间异常检测（PatchTST）是实验性的**，并且是一个**支持性**信号 — 参见 [时间证据（PatchTST）](#时间证据-patchtst)。在运行真正的 Prometheus 序列之前，它会回退到合成/固定历史记录和 z-score；它不是验证的证据，不预测事件。 参见 [路线图](docs/roadmap.md) 以了解下一步计划。 --- ## 贡献 欢迎贡献 — 特别是： - 新的故障场景案例 (`tests/integration/cases/h0NN_*` 格式 — 参见 [测试案例](docs/test-cases.md)) - 信号驱动的测试案例，锻炼 Prometheus、OTel 或 Loki 收集器路径端到端 - LLM 提供商集成 参见 [项目布局](docs/project-layout.md) 以了解代码库结构。 --- ## 社区 KubeVerdict 是开源的，专注于 Kubernetes 事件调查。 欢迎反馈、可复制的故障场景和集成 — 请打开一个问题或开始讨论。 --- ## 许可证 [Apache 2.0](LICENSE)