🤖 AI-Powered Kubernetes Assistant with MCP

Kubernetes Diagnostic MCP

一个只读的 Kubernetes 事件分诊平台，基于 Next.js 构建。它通过官方 Kubernetes JavaScript 客户端收集实时集群状态，运行确定性规则引擎以呈现发现，并可选择生成由 AI 驱动的事件叙述 — 全程不会向集群写入任何内容。

安装： 自托管、OIDC/Keycloak、租户隔离和 Helm。

此版本要求显式配置租户并通过身份验证访问。它不会使用环境中的集群凭据，也不会自动导入旧版共享历史记录。

---

功能

调查和恢复工作流

• Pod 流量路径 — 检查已配置的 Ingress → Service → EndpointSlice → Pod 路由、端口映射、后端状况，以及 Ingress/egress NetworkPolicy 隔离。请参阅 Pod 网络和权限设置。不会收集数据包级流量遥测。
• 历史调查 — 根据保留的事件和快照重建事件时间线，界定当前故障时段，并通过证据链接和确认检查对低置信度调查线索进行排序。可选的、经租户身份验证的 Helm CronJobs 会在事件发生前收集数据。请参阅 历史调查。
• 发生了哪些变化？ — 对比限定范围的快照，查看 Deployment 修订版本、镜像、资源设置、配置指纹、服务路由变化，以及可选的 Prometheus CPU/内存证据。相关性会标记为假设。
• 相关事件 — 使用所有者引用、服务选择器、异常节点位置和故障 PVC 依赖关系对发现进行分组，并为每个关联提供证据。
• 修复并验证 — 提议将受支持的 Deployment 回退至已观察到的健康基线，预览固定版本的 GitOps 清单变更，创建经审核的 GitHub PR，并在合并后验证恢复是否持续。
• 持久化历史记录 — 使用原子磁盘存储，并为修复工作流保留基线和验证证据。

有关 GitHub 目标、可选的 Prometheus、持久化存储、API 示例和恢复契约，请参阅调查工作流设置和限制。

诊断覆盖范围

资源	检测到的故障模式
Pods	CrashLoopBackOff、ImagePullBackOff、OOMKilled、调度失败、探针失败
工作负载	Deployments、StatefulSets、DaemonSets、ReplicaSets、Jobs 未达到预期状态
Services	解析后没有就绪端点的选择器
节点	NotReady、MemoryPressure、DiskPressure、PIDPressure、已封锁调度
HPAs	无法扩缩（AbleToScale=False）、副本数已达到上限
PVCs	Pending（供应器故障）、Lost（底层 PV 已消失）
CronJobs	已暂停且错过计划时间的作业
事件	所有资源类型中存在关联的警告事件

结构化风险和影响模型

除纯文本描述外，每项发现还包含两项结构化评估：

• ImpactAssessment — 范围（pod / workload / service / namespace / node / cluster）、受影响资源引用、受影响副本数、问题是否会影响用户，以及摘要句
• RiskAssessment — 风险级别、置信度、影响范围、忽略风险、修复风险，以及评估依据

此模型用于摘要中的高风险列表，并使 UI 无需解析 Markdown 即可展示结构化上下文。

自然语言查询模式

工程师可以用通俗的英文描述事件，而不必填写表单字段：

“上次部署后，checkout Pod 一直崩溃”

大模型会从描述中提取诊断意图（命名空间、工作负载、关注领域、症状），根据实时集群清单进行验证，并将其解析为具体的 DiagnosticScope。确定性引擎随后照常运行——大模型只负责转换输入，不会生成调查结果。

主要行为：

• 消除歧义 — 如果某个工作负载存在于多个命名空间，工程师可以在运行前通过澄清面板选择
• 推断命名空间 — 如果工作负载名称唯一对应一个命名空间，系统会自动推断（并要求确认）
• 安全防护 — 解析器会在发起任何诊断调用前，根据实际集群验证提取出的命名空间和工作负载名称
• 编辑回退 — “Edit”按钮会将解析出的值预填到表单模式中，方便工程师修正解析结果
• 优雅降级 — 未配置大模型密钥时，查询模式会自动禁用

AI 事件叙述

设置 GROQ_API_KEY 或 OPENAI_API_KEY 且启用 AI 摘要后，确定性调查结果和 Markdown 报告会传递给大模型，以生成：

• 执行摘要
• 附有证据引用的可能根因
• 后续操作
• 只读自动化命令

确定性报告会先返回；仪表板会单独请求可选的叙述内容，因此服务商的延迟不会拖慢证据返回。AI 叙述会在 Report 区域以格式化 Markdown 呈现。系统会指示大模型不得编造资源、命令或原因——它只能解释并排列确定性引擎已发现的内容。没有大模型密钥时，该工具仍可正常使用。

**大模型优先级：**设置 GROQ_API_KEY 时使用 Groq（llama-3.3-70b-versatile）；否则使用 OpenAI（gpt-4o-mini）作为备用。

UI

• Form / Query 切换 — 在结构化表单输入和自然语言查询模式之间切换；偏好设置会保存在 localStorage 中
• 命名空间下拉菜单 — 从实时集群自动填充；无法连接集群时回退为文本输入框
• 工作负载下拉菜单 — 命名空间变更时自动刷新
• 集群上下文选择器 — 无需重启即可在 kubeconfig 上下文之间切换
• 诊断运行历史 — 侧边栏显示近期已持久化的运行记录；点击任一条目即可重新加载其完整结果
• 指标卡片 — Pod 数量、异常 Pod、警告事件、节点健康状况、PVC 健康状况、AI 状态
• 调查结果面板 — 显示前 6 项调查结果，包含严重性标记、证据列表和只读命令
• 渲染后的 Markdown 报告 — AI 叙述或确定性报告会渲染标题、代码块、表格和列表

API

方法	路径	描述
POST	/api/mcp	运行诊断
GET	/api/mcp	能力清单
POST	/api/nlq/parse	将自然语言查询解析为 DiagnosticScope
GET	/api/nlq/parse	检查 NLQ 模式是否可用
GET	/api/namespaces	列出集群命名空间
GET	/api/workloads?namespace=	列出某个命名空间中的工作负载
GET	/api/contexts	列出 kubeconfig 上下文
GET	/api/history	列出近期诊断运行记录
GET	/api/history/:id	按 ID 获取完整运行记录
POST	/api/history/:id/narrative	为已保存的证据生成可选的 AI 叙述
GET	/api/health	健康检查（不访问集群，供 k8s 探针使用）

身份验证与隔离

• 通用 OIDC 登录，附带 Keycloak 配置指南；验证授权码、PKCE、state、nonce 和签名的 ID 令牌。
• 租户工作区，设有查看者／操作员／管理员角色、独立的 Kubernetes 凭据和命名空间允许列表。
• 按租户划分历史记录、基线、修复计划和集成配置。
• 用于自动化的租户 API 密钥；不使用共享全局密钥，也不允许匿名访问。
• 按身份和租户设置速率限制，限制并发采集量，对 Kubernetes 读取操作分页并设置截止时间。
• 以非 root 用户部署 Helm，使用 PVC、只读凭据挂载、入口策略，以及独立的就绪和存活检查。

安装或开发

按照安装指南配置租户凭据、设置 OIDC 提供方、创建 Secrets 并安装捆绑的 Helm chart。源代码仓库即为下载来源；请在自己的注册表中构建镜像。不会自动发布版本或镜像。

进行本地开发时，在 .env.local 中配置 APP_URL=http://localhost:3000 和 TENANTS_CONFIG_FILE，并提供明确指定的租户 kubeconfig，以及 OIDC 或租户 API 密钥，然后运行：

npm ci
npm run dev

验证

npm test
npm run typecheck
npm run build

测试覆盖确定性诊断、租户隔离、身份验证／CSRF／角色、签名 OIDC 令牌验证、工作负载所有权、受限采集和经审核的恢复工作流。CI 还会检查容器构建、生产依赖项审计和 Helm chart。

环境变量

变量	用途
APP_URL	规范应用源；生产环境中必须使用 HTTPS
TENANTS_CONFIG_FILE	必需的、由管理员管理的租户 JSON 配置
OIDC_ISSUER、OIDC_CLIENT_ID、OIDC_CLIENT_SECRET	浏览器登录提供方配置
OIDC_GROUPS_CLAIM	顶层 ID 令牌数组声明；默认为 groups
OIDC_SCOPES	默认为 openid profile email
DIAGNOSTICS_DATA_DIR	持久化租户记录和服务端会话；默认为 .data
DIAGNOSTICS_HISTORY_LIMIT	每个租户未固定的历史记录保留数量；默认值为 200，最大值为 2,000
GROQ_API_KEY、GROQ_MODEL	可选的 AI 提供方；要求租户启用 allowAi
OPENAI_API_KEY、OPENAI_MODEL	可选的备用 AI 提供方；要求租户启用 allowAi
APP_VERSION、BUILD_ID	健康检查端点元数据

GitHub 和 Prometheus 凭据／目标按租户配置。请参阅集成配置。

---

API 参考

POST /api/mcp

curl -X POST https://mcp-diagnostics.127.0.0.1.nip.io/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "agent": "kubernetes-diagnoser",
    "goal": "Find why checkout is failing",
    "input_context": {
      "namespace": "team-a",
      "workload": "checkout",
      "context": "team-a",
      "includeLogs": true,
      "includeNodes": false,
      "includeHpa": true,
      "enableAiSummary": false,
      "tailLines": 120,
      "maxPods": 60
    }
  }'

input_context 字段

字段	类型	默认值	说明
namespace	string	default	要检查的命名空间
context	string	租户上下文	必须与配置的租户集群匹配
workload	string	—	按工作负载名称筛选
labelSelector	string	—	标准标签选择器，例如 app=checkout
includeLogs	boolean	true	收集不健康 Pod 的日志
includeNodes	boolean	false	收集节点状况（需要 ClusterRole）
includeHpa	boolean	true	收集 HPA 状态
enableAiSummary	boolean	false	生成 AI 叙述
tailLines	number	120	每个容器的日志行数（20–500）
maxPods	number	60	最多采集的 Pod 数量（1–200）

响应结构

{
  "requestId": "uuid",
  "status": "ok | partial | failed",
  "generatedAt": "ISO-8601",
  "summary": {
    "health": "healthy | degraded | critical",
    "totalPods": 12,
    "unhealthyPods": 2,
    "notReadyNodes": 0,
    "pendingPvcs": 1,
    "warningEvents": 5,
    "criticalFindings": 0,
    "highFindings": 2,
    "topRisks": ["[HIGH] checkout is crash-looping: pod will not recover without a fix"]
  },
  "findings": [
    {
      "id": "pod-production-checkout-0-crashloop",
      "severity": "critical",
      "category": "runtime",
      "title": "Container app is in CrashLoopBackOff",
      "resource": { "kind": "Pod", "namespace": "team-a", "name": "checkout-0" },
      "signal": "CrashLoopBackOff",
      "evidence": ["Restart count: 10", "Last exit code: 1"],
      "impact": "Pod is not serving traffic.",
      "recommendedActions": ["Check logs for the root cause", "..."],
      "automation": [{ "command": "kubectl logs ...", "destructive": false, "requiresApproval": false }],
      "impactAssessment": { "scope": "workload", "userFacing": true, "summary": "..." },
      "riskAssessment": { "level": "critical", "confidence": "high", "riskIfIgnored": "...", "blastRadius": "workload", "reasons": ["..."] }
    }
  ],
  "runbook": ["Step 1...", "Step 2..."],
  "output": "# Kubernetes Diagnostic Report\n...",
  "snapshot": { /* full raw cluster state */ },
  "metadata": { "aiStatus": "success | skipped | disabled | failed", "model": "llama-3.3-70b-versatile" }
}

POST /api/nlq/parse

将自然语言事件描述解析为经过验证的 DiagnosticScope。

curl -X POST https://mcp-diagnostics.127.0.0.1.nip.io/api/nlq/parse \
  -H "Content-Type: application/json" \
  -d '{ "query": "checkout pods keep crashing since last deploy", "context": "kind-test-cluster" }'

响应（已解析）

{
  "intent": { "namespace": "team-a", "workload": "checkout", "focus": ["pods", "logs"], "confidence": "high", ... },
  "resolvedContext": { "namespace": "team-a", "workload": "checkout", "includeLogs": true, ... },
  "requiresConfirmation": false,
  "confirmationPrompt": null
}

响应（有歧义）

{
  "intent": { ... },
  "resolvedContext": null,
  "requiresConfirmation": true,
  "confirmationPrompt": "Found 'checkout' in 2 namespaces: production, staging.",
  "clarificationOptions": {
    "field": "namespace",
    "prompt": "Choose a namespace for \"checkout\".",
    "options": [
      { "label": "production", "value": "production", "resolvedContext": { ... } },
      { "label": "staging", "value": "staging", "resolvedContext": { ... } }
    ]
  }
}

未配置 LLM 密钥时返回 503。请先调用 GET /api/nlq/parse 检查可用性。

---

项目结构

├── agents/
│   └── mcpAgentRunner.ts           # Orchestrates collection → analysis → AI → history
├── app/
│   ├── api/
│   │   ├── mcp/route.ts            # POST /api/mcp
│   │   ├── nlq/parse/route.ts      # POST /api/nlq/parse, GET /api/nlq/parse
│   │   ├── namespaces/route.ts     # GET  /api/namespaces
│   │   ├── workloads/route.ts      # GET  /api/workloads
│   │   ├── history/route.ts        # GET  /api/history
│   │   ├── history/[id]/route.ts   # GET  /api/history/:id
│   │   ├── contexts/route.ts       # GET  /api/contexts
│   │   └── health/route.ts         # GET  /api/health
│   └── page.tsx                    # Dashboard UI (form + query modes)
├── lib/
│   ├── diagnostics/
│   │   ├── analyzer.ts             # Deterministic Kubernetes rules engine
│   │   ├── formatter.ts            # Markdown report and summary builder
│   │   └── __tests__/
│   │       └── analyzer.test.ts    # 27 unit tests, no kubeconfig needed
│   ├── nlq/
│   │   ├── types.ts                # ExtractedIntent, NLQParseResponse, ClusterInventory
│   │   ├── parser.ts               # LLM call + Zod schema validation
│   │   ├── resolver.ts             # Deterministic parameter validation
│   │   ├── prompt.ts               # Prompt construction
│   │   ├── inventory.ts            # Cluster namespace + workload fetcher
│   │   └── __tests__/
│   │       ├── parser.test.ts      # JSON parsing and schema validation
│   │       └── resolver.test.ts    # Resolution logic, no LLM needed
│   ├── llm/
│   │   └── client.ts               # Groq → OpenAI client builder
│   ├── kubernetes/
│   │   └── collector.ts            # Kubernetes API client and snapshot builder
│   ├── store/
│   │   └── history.ts              # Persistent run history and baseline selection
│   ├── ratelimit.ts                # Bounded fixed-window rate limiter
│   └── validation.ts               # Zod request schema and normalisation
├── lib/auth/                       # OIDC, server sessions and route authorization
├── lib/tenancy/                    # Identity bindings, roles and scope authorization
├── deploy/helm/                    # Supported self-hosted installation
├── types/
│   └── mcp.ts                      # Full TypeScript type contract
├── k8s/                            # Kubernetes manifests
│   ├── namespace.yaml
│   ├── rbac.yaml
│   ├── deployment.yaml
│   ├── ingress.yaml
│   └── secret.example.yaml
├── vitest.config.ts                # Test configuration
└── Dockerfile                      # Multi-stage production build

---

RBAC 要求

每个租户使用专用的只读凭据，且仅限访问为其配置的命名空间。请从命名空间 Role/RoleBinding 示例开始。应用服务账户没有集群范围的权限，也不会自动挂载令牌。访问节点需要显式的租户功能权限和额外的集群级权限。

有关凭据轮换、隔离检查、存储限制、从共享历史记录迁移以及共享托管路线图，请参阅自托管指南。