K8gentS — Kubernetes RCA MCP Server

K8gentS ☸️🤖

面向 Kubernetes 的人在回路 RCA Agent——LLM 诊断，OPA 限界的修复

---

📖 概述

K8gentS 是一个 Kubernetes 诊断 Agent，其核心理念是：LLM 擅长推理集群故障，但不适合在无人监督的情况下对其采取行动。它会持续监控集群事件流，将 Warning 级事件交由 Gemini 驱动的**根因分析（RCA）流程处理，并将最有可能的假设及解决步骤发送到 Slack。每项修复都采用人在回路（HITL）**方式——在发生任何变更之前，由审核者通过交互式按钮批准或拒绝。获批的修复会在临时 Job 中执行，其影响范围由 API 服务器上的 OPA Gatekeeper 准入策略限定，独立于 RBAC。推理过程有意设计为非确定性的；与之配套的控制措施则不是。

目标：缩短可诊断故障的 MTTR，而不把 kubectl apply 交给 LLM。

---

🧠 难题所在

构建 Kubernetes 部分并不复杂。真正的挑战在于：当底层引擎本质上具有非确定性时，如何让诊断层值得信赖。

传统可观测性建立在各种保证之上。告警会在已知阈值触发。仪表板会显示可复现的数据。针对同一查询，日志会返回一致的答案。SRE 的成功依赖这种可预测性——它让事件响应能够重复执行，也让值班工作可持续。

由 LLM 驱动的诊断层打破了这种约定。同一个 Pod 故障，在三次不同运行中可能产生三种不同但看似合理的解释。每种解释都可能逻辑自洽，甚至在不同假设下都可能正确。但“看似合理”不等于“正确”，而对于基础设施来说，两者之间的差距正是故障发生之处。

构建 K8gentS 时，我一直在思考以下一些具体问题：

1. 如何在无界输出空间中评估置信度。 Agent 会返回排名前 3 的根因及置信度指标，但究竟对什么的置信度？模型并非从固定的一组已知故障模式中选择，而是在自由生成假设。校准后的置信度分数需要参考分布，而这里的分布就是模型本次运行碰巧生成的内容。

2. 何时相信推理，何时退回确定性检查。——这是一门艺术 某些故障（CrashLoopBackOff、OOMKilled）有成熟的诊断路径，确定性检查每次都能得出正确结果。另一些故障则能从模型根据多个信号进行推断的能力中受益。划定这条界线——并在运行时做到这一点——并不简单，这正是其中真正的艺术所在。

3. 如何评估一个本应发现未预料故障的 Agent。 标准的 ML 评估方法假设你知道“正确”是什么样的。对于诊断 Agent，其价值部分在于发现新颖的故障模式——按定义，这些故障是你无法预先列举的。那么，如何判断什么是错的、什么是对的？

4. “集群中的工具”问题。 如何监控监控器？目前，该服务计划作为集群中的服务运行；但如果服务本身导致资源耗尽，或自身发生故障，该怎么办？如何判断服务本身是否就是问题的根源？

5. 如何为这个问题选择合适的模型。 市面上还有许多其他类型的机器学习模型，那么，非确定性的大语言模型真的是正确选择吗？还是说，其他模型更适合基础设施类问题？

这些都是我正在积极探索的问题。如果你已经解决了其中任何一个，或者能提出比我更清晰的表述，我很希望听到你的想法。

---

✨ 核心职责

1. 持续监控： 监视集群中的错误事件、崩溃的 Pod、CrashLoopBackOff 状态、OOMKilled 事件，以及 Connectivity/DNS、Database Deadlock 或 Secret/Config Missing 等其他故障情况。
2. 自动根因分析（RCA）： 检测到异常后，安全地获取相关上下文（近期日志、Pod 描述、事件历史记录），清除其中的机密信息和个人身份信息（PII），然后将这些上下文发送至基于大模型的推理引擎。
3. 通知与置信度评分： 通过 Socket Mode 向指定的 Slack 通信频道发送通知，内容包括：
   • 错误的描述性摘要。
   • 最可能的 3 个根因，每个根因都附有置信度指标。
   • 分步解决说明。
4. 交互式修复（选择启用）： 通过 Slack 中的交互式按钮直接提示用户："批准修复" 或 "我将手动处理"。
   • 默认状态 — 只读： Agent 严格保持只读，因此默认情况下具有极高的安全性。

---

🛠️ 架构与安全

该 Agent 的设计让每一层都能独立限制影响范围——这并非为了冗余而冗余，而是因为在推理引擎具有非确定性的情况下，任何单一控制措施都不足以确保安全。

层	机制	防范内容
Pod 安全	runAsNonRoot、只读文件系统、移除所有 Linux 功能	容器逃逸、权限提升
RBAC	Agent Pod 严格只读；写入操作仅由 k8gent-executor-sa 执行	Agent 遭到入侵后修改集群
临时执行器	通过 k8gent-executor-sa 创建短生命周期 Job；ttlSecondsAfterFinished=120	修复后留下持久立足点
OPA Gatekeeper	在 API 服务器准入层强制执行 Rego 策略	执行器越权，即使 RBAC 配置错误也能防止
日志清理	使用正则表达式扫描器，在调用大模型前移除 IP、JWT、API 密钥和电子邮件地址	通过大模型提示词泄露机密信息
速率限制	按小时触发熔断，并对事件进行去抖处理	因噪声导致 API 配额耗尽
无 Ingress 通信	Slack Socket Mode；不暴露端点或配置 Ingress 规则	入站攻击面

OPA Gatekeeper 策略（定义于 deploy/helm/k8gents/templates/opa-gatekeeper/）明确禁止执行器服务账户修改 serviceAccountName、启用 hostNetwork 或 hostPID、在 kube-system 中操作，或修改 Pod 和 Deployment 以外的任何资源类型——该策略直接在 Kubernetes API 准入层强制执行，不依赖 RBAC。

---

🚀 部署

K8gentS 以 Helm chart 形式提供。OPA Gatekeeper 是声明式 chart 依赖项——安全沙箱会与 Agent 一同自动安装。

先决条件

• Kubernetes v1.20+、Helm 3
• 已通过身份验证并连接到目标集群的 kubectl
• Google Gemini API 密钥（AI_API_KEY）
• 已启用 Socket Mode 的 Slack 应用（生成以 xoxb- 开头的 SLACK_BOT_TOKEN 和以 xapp- 开头的 SLACK_APP_TOKEN）
• Slack 频道 ID（SLACK_CHANNEL_ID）以及以逗号分隔的 Slack 审批者用户 ID 列表（ALLOWED_APPROVERS）

1. 配置 Slack

1. 在 api.slack.com 创建 Slack App。
2. 启用 Socket Mode → 生成应用级令牌（xapp-...）。
3. 启用 交互式组件。
4. 添加 chat:write 和 chat:write.public OAuth 权限范围 → 生成 Bot 令牌（xoxb-...）。
5. 邀请 Bot 加入告警频道，并从频道设置中复制频道 ID。

2. 构建并推送 Agent 镜像

docker build -t your-registry/k8gent:latest .
docker push your-registry/k8gent:latest

更新 deploy/helm/k8gents/values.yaml 中的 image.repository，使其与您的镜像仓库路径一致。

3. 通过 Helm 安装

# Fetch chart dependencies (downloads OPA Gatekeeper)
helm dependency update deploy/helm/k8gents

# Install — secrets are injected at deploy time, never stored in source
helm install k8gents deploy/helm/k8gents \
  --namespace k8gent-system \
  --create-namespace \
  --set secrets.aiApiKey="YOUR_GEMINI_KEY" \
  --set secrets.slackBotToken="xoxb-..." \
  --set secrets.slackAppToken="xapp-..." \
  --set secrets.slackChannelId="C12345678" \
  --set secrets.allowedApprovers="U123456,U789012"

若要停用 OPA 沙箱（如果您的集群已运行 Gatekeeper 并使用自己的策略）：

--set sandbox.enabled=false --set gatekeeper.enabled=false

4. 验证安装

kubectl logs -l app=k8gents -n k8gent-system -f

您应该能看到监视器已连接到集群 API，并且 Slack Socket Mode 连接已初始化。

---

⚙️ 配置

关键环境变量（通过 Helm 中的 --set agent.* 设置；本地运行时也可直接设置）：

变量	默认值	描述
WATCH_NAMESPACES	all	要监控的命名空间，以逗号分隔；设为 all 则监控整个集群
AI_MODEL	gemini-2.5-pro	Google GenAI SDK 支持的任意模型名称
LOG_LEVEL	INFO	Python 日志级别
REMEDIATION_MODE	api	api（Kubernetes 客户端，适合在集群内安全运行）或 subprocess（kubectl，仅用于本地开发）

更改 AI_MODEL 无需修改代码——Agent 会通过配置的模型名称动态路由所有大模型调用。

---

🔮 接下来

已实现且可正常运行的功能：

• 监控 → 诊断 → 发送带置信度评分的 Slack 通知
• 通过 Slack 交互按钮实现人工审核后再修复
• 配备 OPA Gatekeeper 准入沙箱的临时 Job 执行器
• MCP 服务，供 AI 客户端按需进行诊断——已在 MCP Registry 上发布，名称为 io.github.JDoornink/k8gents
• 将 Gatekeeper 设为硬性依赖的 Helm chart

尚未真正解决的问题：

• 置信度校准——当前评分反映的是模型自我报告的确定性，与实际准确率并无可靠的相关性。
• 确定性路由——可按规范诊断的故障（CrashLoopBackOff、OOMKilled）不应经过大模型处理。下一项结构性改进，是构建一个可靠的运行时分类器，用于区分“有已知答案”和“需要推理”的情况。
• 评估——对旨在捕获新型故障的 Agent 进行回归测试，需要一个目前尚未完全适用于该问题领域的框架。注入合成故障（混沌工程）是最有前景的方向，但其覆盖范围本质上有限。
• 修复后的验证——执行修复后，监控目标命名空间 60s，并发布后续 Slack 主题串，确认已恢复或标记崩溃状态仍在持续。