AI导哈

Kubernetes集群观测工具

一款用于监控Kubernetes集群事件、提供集群健康状态分析的可观测性工具，支持通过LLM生成自然语言解释。

  • by 0x0BSoD
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 0x0BSoD/mcp-k8s

使用说明

mcp-k8s

Kubernetes可观察性工具，用于监视集群事件，用所有权上下文丰富它们，并回答有关集群健康的问题——可选地使用LLM叙述的解释。

建筑

┌─────────────────────────────────┐        ┌──────────────────────────────┐
│          Coordinator            │  gRPC  │        Cluster Agent         │
│  (central brain, HTTP API)      │◄──────►│  (in-cluster sensor)         │
│                                 │        │                              │
│  ┌──────────┐  ┌────────────┐   │        │  ┌────────┐  ┌───────────┐   │
│  │  Planner │  │ Correlator │   │        │  │ Watcher│  │   Store   │   │
│  └──────────┘  └────────────┘   │        │  └────────┘  └───────────┘   │
│  ┌──────────┐  ┌────────────┐   │        │  ┌──────────────────────┐    │
│  │ Executor │  │ LLM client │   │        │  │      Enricher        │    │
│  └──────────┘  └────────────┘   │        │  └──────────────────────┘    │
└─────────────────────────────────┘        └──────────────────────────────┘
  • 集群代理 --在每个集群内运行。通过告密者监视Kubernetes事件，用所有者链（Pod→副本集→部署），将它们存储在环形缓冲区中，并公开gRPC API。
  • 协调员 --在集群外部（或在一个中心集群中）运行。接收HTTP查询，构建基于规则的执行计划，扇出对已注册集群代理的gRPC调用，关联结果，并返回结构化JSON——可选地带有LLM叙述的解释。

层边界是一个严格类型的gRPC契约。协调员从不要求代理人思考；它只要求数据。

特性

  • 事件时间线重建 --分别对突发事件进行重复数据消除和排序（每个密钥最多5个）
  • 所有者链丰富 --追踪Pod→RS→部署并揭示工作负载的根本原因
  • 对象快照 --容器状态、重启计数、上次终止原因、工作负载条件
  • 集装箱日志 --最后N行按需提取
  • Pod指标 --CPU（毫核）和内存（字节）通过指标服务器；当度量服务器不存在时，优雅地禁用
  • 因果关系 --跨命名空间将下游事件链接到其根本原因
  • LLM叙事 --可选Ollama集成：自然语言问题→ 结构化意图→ 管道→ 叙述式回答

API

POST/query——结构化查询

{
  "cluster_name": "prod",
  "namespace": "default",
  "intent": "ExplainRestarts",
  "since_minutes": 60,
  "mode": "incident-summary"
}

意向： NamespaceOverview | ExplainObjectIssue | ExplainRestarts | BuildTimeline

模式： technical （默认）| concise | incident-summary

对于 ExplainObjectIssue，还提供 object_kind 和 object_name.

POST/ask——自然语言查询（需要Ollama）

{
  "cluster": "prod",
  "namespace": "default",
  "question": "why are the redis pods restarting?",
  "mode": "concise"
}

LLM从问题中提取结构化意图，运行与 /query，然后叙述研究结果。响应包括两者 answer （叙事字符串）和完整的结构化响应对象。

退货 503 当 OLLAMA_BASE_URL 未配置。

POST/registry——注册集群代理

{
  "cluster_name": "prod",
  "grpc_endpoint": "mcp-cluster-agent.mcp-system.svc:50051"
}

需要 Authorization: Bearer <token> 当 MCP_REGISTRY_TOKEN 已设置。

DELETE/注册表/{cluster}

注销群集。相同的身份验证要求。

GET/注册表

列出所有已注册的集群。

GET/健康

退货 {"status": "ok"}.

响应形状

{
  "cluster": "prod",
  "mode": "technical",
  "namespace_summary": [...],
  "timeline": [...],
  "root_causes": [...],
  "affected_objects": [...],
  "snapshots": [...],
  "container_logs": [...],
  "pod_metrics": [...],
  "summary": "...",
  "warnings": [],
  "answer": "..."
}

warnings 当某些步骤失败但收集了部分数据时，它不是空的。HTTP状态为 207 Multi-Status 当所有步骤都失败并且没有收集到任何东西时。

配置

集群代理

环境变量 默认值 描述
MCP_CLUSTER_NAME （必填） 用于标识此群集的名称
MCP_GRPC_ADDR :50051 gRPC侦听地址
MCP_WATCH_NAMESPACE "" （all） 将事件监视限制为一个命名空间
MCP_STORE_MAX_SIZE 10000 环形缓冲容量

协调员

环境变量 默认值 描述
MCP_HTTP_ADDR :8080 HTTP侦听地址
MCP_REGISTRY_TOKEN "" （无身份验证） 注册表突变的共享密钥
MCP_REGISTRY_FILE "" （内存中） 持久群集注册表的路径
OLLAMA_BASE_URL "" （禁用） Ollama基本URL，例如。 http://localhost:11434
OLLAMA_MODEL llama3 与Ollama一起使用的型号名称

构建

make build          # build both binaries into bin/
make test           # run all tests
make proto          # regenerate gRPC code from proto/clusteragent.proto
make docker         # build both Docker images

需要Go 1.21+， protoc, protoc-gen-go，以及 protoc-gen-go-grpc 对于原始世代。

部署

make deploy         # kubectl apply deploy/namespace.yaml, cluster-agent/, coordinator/
make undeploy       # tear it all down

一切都落在 mcp-system 命名空间。每个集群部署一个集群代理，在任何地方部署一个协调器，可以访问所有代理的网络。

部署后，向协调器注册每个代理：

curl -s -X POST http://<coordinator>:8080/registry \
  -H 'Content-Type: application/json' \
  -d '{"cluster_name":"prod","grpc_endpoint":"mcp-cluster-agent.mcp-system.svc:50051"}'

本地开发

# Terminal 1 — cluster agent (needs KUBECONFIG pointing at a real cluster)
MCP_CLUSTER_NAME=local ./bin/cluster-agent

# Terminal 2 — coordinator
./bin/coordinator

# Register the local agent
curl -s -X POST http://localhost:8080/registry \
  -H 'Content-Type: application/json' \
  -d '{"cluster_name":"local","grpc_endpoint":"localhost:50051"}'

# Structured query
curl -s -X POST http://localhost:8080/query \
  -H 'Content-Type: application/json' \
  -d '{"cluster_name":"local","namespace":"payments","intent":"ExplainRestarts","since_minutes":30,"mode":"incident-summary"}' | jq

# Natural language query (requires Ollama)
OLLAMA_BASE_URL=http://localhost:11434 ./bin/coordinator &
curl -s -X POST http://localhost:8080/ask \
  -H 'Content-Type: application/json' \
  -d '{"cluster":"local","question":"why are pods crashing in the payments namespace?"}' | jq .answer

gRPC方法

方法 说明
ListEvents 存储中的事件，可选择按命名空间/原因/时间进行筛选
GetEventsForObject 特定类型+名称的所有事件
GetNamespaceSummary 命名空间按原因分组的事件计数
ResolveOwnerChain 从资源到其工作负载根的所有者引用链
GetObjectSnapshot 对象的当前状态（阶段、容器状态、条件）
GetContainerLogs 容器的最后N行日志
GetPodMetrics 通过指标服务器计算Pod的CPU/内存使用情况

相关 MCP