kubently

Kubently

Kubently — 以 Agentic 方式排查 Kubernetes 故障

概述

Kubently（Kubernetes + Agentically）是一款免费、可自托管、厂商中立的多集群 Kubernetes 故障排查工具。只需提出一个问题，即可并行获取整个集群群组中所有集群经 AI 诊断后的答案——包括无法直接访问的集群：执行器会主动向外连接中央 API，因此无需入站入口、共享 kubeconfig 或分发每个集群的凭据。

Agent 通过 A2A（Agent-to-Agent）协议协作，任何 MCP 客户端（Claude Code、Cursor、Claude Desktop）都可以直接将 Kubently 用作工具。

主要功能

• 多集群群组故障排查：一个问题即可并行分发到所有已注册集群
• 主动拨号的执行器：可访问位于防火墙/NAT 后的集群——无需入站入口或共享 kubeconfig
• 自然语言界面：以对话方式排查和调试 Kubernetes 问题
• 全面分析：自动检测问题、分析根本原因并推荐解决方案
• 多 LLM 支持：兼容 Google Gemini、OpenAI、Anthropic 和其他提供商
• A2A 协议：业界标准的 Agent 间通信，支持复杂工作流
• MCP 服务：可选的 Model Context Protocol 端点，让 MCP 客户端（Claude Desktop、Cursor、自定义 Agent）直接访问工具
• 安全优先：支持 API 密钥认证、OAuth/OIDC 和使用 cert-manager 的 TLS
• 持久会话：由 Redis 支持的对话历史和上下文管理
• 丰富的工具套件：集成 kubectl、日志分析、资源检查等

快速开始

面向用户：5 分钟上手

将 kubectl 指向任意集群（kind、minikube 或实际集群），然后运行：

npm install -g @kubently/cli
kubently install

就这么简单。CLI 会通过 Helm 安装 Kubently、配置密钥和执行器、为 API 设置端口转发，并打开调试对话：

kubently> why is my nginx pod crashlooping?

你需要一个 LLM API 密钥（Anthropic、OpenAI 或 Google）——安装程序会提示你输入，或从环境变量 ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY 中读取。使用 --provider 选择 LLM，使用 --chart ./deployment/helm/kubently 从本地检出版本安装，并通过 kubently install --help 查看其他选项。

在 Claude Code / Cursor 中使用（MCP）

已经运行过 kubently install？将 Kubently 添加到 Claude Code：

claude mcp add kubently -- kubently mcp

或者直接通过 HTTP 连接（无需桥接进程）：

claude mcp add --transport http kubently http://localhost:8080/mcp/ \
  --header "X-API-Key: <your-api-key>"

然后可以向 Claude 提问，例如 “使用 kubently 查明 payments 的 Pod 为何陷入崩溃循环”。任何 MCP 客户端都能使用——Cursor 和通用配置请参阅 docs/MCP.md。

主动诊断（Alertmanager → Slack）

将 api.env.SLACK_WEBHOOK_URL 设置为 Slack 入站 Webhook URL，并将 Alertmanager 指向 Kubently：

receivers:
  - name: kubently
    webhook_configs:
      - url: https://<your-kubently-host>/webhooks/alertmanager
        http_config:
          http_headers:            # Alertmanager >= 0.28
            X-API-Key:
              secrets: ["<your-api-key>"]

每个触发的告警都会由 Agent 诊断，并将结果发送到 Slack——机器人通常会在你打开笔记本电脑前就解释根本原因。

定时集群健康摘要

告警是被动响应的。健康摘要会按计划扫描所有已注册集群，并将一条摘要发送到同一个 Slack webhook——健康集群会合并为一行，剩下的就是需要你关注的内容。

fleetReport:
  enabled: true
  schedule: "0 13 * * 1-5"   # weekday mornings

在安排计划前先预览——dry_run 会返回摘要，但不会发送：

curl -X POST https://<your-kubently-host>/webhooks/fleet-report \
  -H "X-API-Key: <your-api-key>" -H 'Content-Type: application/json' \
  -d '{"dry_run": true}'

健康摘要的问题由你决定。可在该请求中传入 query，立即试用，然后通过 values 中的 fleetReport.query 保留你满意的表述：

fleetReport:
  query: |-
    Check every cluster for pods restarting more than 5 times and for PVCs above
    85% usage. One line per healthy cluster. No preamble.

要真实运行一次定时流程——包括镜像、密钥、集群内 URL 等：

kubectl create job --from=cronjob/kubently-fleet-report fleet-report-test -n kubently

部署验证（这次部署真的成功了吗？）

告诉 Kubently 你刚刚部署了什么，它就会监控滚动更新直至完成，然后开展实际调查——Pod 是否就绪？事件是否正常？新日志中是否有错误？指标相较于部署前的时间窗口是否退化（配置了 Prometheus 时）？——最后将包含证据的 PASS/FAIL 判定发送到 Slack。将它接入 CI 流水线的最后一步：

curl -X POST https://<your-kubently-host>/webhooks/verify-deployment \
  -H "X-API-Key: <your-api-key>" -H 'Content-Type: application/json' \
  -d '{"cluster": "prod-east", "namespace": "shop",
       "workload": "deploy/checkout-api", "context": "v1.42.0"}'

添加 "dry_run": true，即可同步获取判定，而不会发送消息。没有 CI 访问权限？也可以为工作负载添加标签——kubently.io/verify=enabled——并在 values 中启用 verifyDeployment.watch：Kubently 会发现每次 generation 变更，并主动验证滚动更新。

定时检查（按 cron 计划重复提问）

健康摘要会提出一个宽泛的问题。定时检查则让你按自己的计划提出自己的问题——每项检查都是一个命名提示词，包含 cron 计划和可选的目标集群，由 Agent 执行并发送到 Slack：

scheduledChecks:
  enabled: true
  checks:
    - name: cert-expiry
      schedule: "0 8 * * 1"        # Monday mornings
      prompt: |-
        Check TLS secrets for certificates expiring within 21 days.
        List each as namespace/name with days remaining.
    - name: pvc-pressure
      schedule: "0 */6 * * *"
      clusters: [prod-east]
      prompt: Find PersistentVolumeClaims above 85% usage.

检查通过时不会发送任何内容——保持安静就表示一切正常（将 notifyOnPass: true 设为也接收通过通知）。失败时则始终会发送通知，并附上证据。无需等待 cron，即可迭代调整检查：

curl -X POST https://<your-kubently-host>/webhooks/scheduled-check \
  -H "X-API-Key: <your-api-key>" -H 'Content-Type: application/json' \
  -d '{"check": "cert-expiry", "dry_run": true}'

📖 完整快速入门指南请参阅 QUICK_START.md

📚 生产环境部署请参阅 GETTING_STARTED.md

面向开发者：本地测试

# Deploy to a local kind cluster (builds images from HEAD)
ANTHROPIC_API_KEY=sk-... ./deployment/scripts/kind-e2e.sh

# Run comprehensive test suite
./test-automation/run_tests.sh test-and-analyze --api-key test-api-key

📖 开发指南请参阅 CLAUDE.md

配置

LLM 提供商

通过 LLM_PROVIDER 选择提供商，并提供该提供商的密钥。没有默认提供商——未设置 LLM_PROVIDER 时，Agent 会拒绝启动。使用 deployment/docker-compose.yaml 进行本地开发时，请将两者都放入 .env（参见 deployment/.env.example）：

# Anthropic
LLM_PROVIDER=anthropic-claude
ANTHROPIC_API_KEY=your-anthropic-api-key

# OpenAI (also matches Azure and OpenAI-compatible endpoints)
LLM_PROVIDER=openai
OPENAI_API_KEY=your-openai-api-key

# Google Gemini
LLM_PROVIDER=google-gemini
GOOGLE_API_KEY=your-gemini-api-key

在 Kubernetes 中，密钥来自 kubently-llm-secrets secret，而 LLM_PROVIDER 则放在 api.env 下。

Helm 部署

使用 Helm values 自定义部署：

Kubently 以单个 chart 发布。通过 api.enabled、redis.enabled 和 executor.enabled 启用或禁用各组件——在远程集群上仅安装 executor，也使用同一个 chart，只需禁用前两个组件。

# From a checkout
helm install kubently ./deployment/helm/kubently -n kubently \
  -f deployment/helm/test-values.yaml

# Or from the published chart repository
helm repo add kubently https://kubently.github.io/kubently
helm install kubently kubently/kubently -n kubently -f my-values.yaml

LLM_PROVIDER 为必填项，且 chart 未设置默认值——请在 api.env 下设置（anthropic-claude、openai 或 google-gemini）。完整配置项请参阅 ENVIRONMENT_VARIABLES.md，生产环境部署指南请参阅 GETTING_STARTED.md。

运维手册

将组织的经验知识融入调查。运维手册是手写的 Markdown 文件，带有轻量级 frontmatter；当调查（聊天问题、Alertmanager 告警或 A2A 调用）符合某个运维手册的条件时，Agent 会将其作为“此情境下的运维手册”接收，在适用时遵循其中的指引，记录偏差，并在诊断中按名称引用。

示例：

---
name: Payments CrashLoopBackOff
match:
  alerts: ["KubePodCrashLooping", "PaymentsPod*"]   # alert-name globs
  namespaces: ["payments", "payments-*"]            # namespace selectors
  workloads: ["payment-api*"]                       # matches derived pod names too
  topics: ["crashloop", "OOMKilled", "payment service"]  # free-text tags
---
1. Check recent deploys first: payment-api ships through ArgoCD, and 90% of
   crashloops here follow a bad config sync.
2. OOMKilled almost always means the JVM heap flag drifted from the container
   memory limit — compare `-Xmx` against `resources.limits.memory` before
   blaming traffic.
3. If the DB connection pool is exhausted, do NOT restart the pods; escalate
   to #payments-oncall (restarts thundering-herd the database).

通过 Helm 值部署运维手册（它们会成为挂载到 API pod 中的 ConfigMap；编辑后无需重启 pod 即可生效）：

# production-values.yaml
runbooks:
  payments-crashloop.md: |
    ---
    name: Payments CrashLoopBackOff
    match:
      alerts: ["KubePodCrashLooping"]
      namespaces: ["payments"]
    ---
    1. Check recent deploys first ...

匹配结果按分数排序：告警名称匹配优先于命名空间／工作负载选择器匹配，后者又优先于主题匹配。最佳匹配项会首先注入，注入的总大小上限为（KUBENTLY_RUNBOOKS_MAX_CHARS，默认 8000 个字符）——一份完整的最佳匹配手册胜过多份手册的片段。在 Helm 之外，可将 KUBENTLY_RUNBOOKS_DIR 指向包含 .md 文件的任意目录。

事件历史

过去的诊断会成为可搜索的机构记忆。每当调查得出根本原因时，Kubently 会在 Redis 中存储一条精简记录，包含日期、集群、涉及的资源、症状关键词、根因的一句话摘要，以及已说明的解决方案；记录按经过身份验证的调用方隔离（与对话记忆使用相同的命名空间边界，因此在多租户部署中，一个租户的事件对其他租户不可见）。

历史记录有两种用途：

• Agent 的 search_past_incidents 工具可回答“以前遇到过这种情况吗？”——按资源、集群、症状和根因文本搜索关键词，并按时间从新到旧排列。
• 自动呈现：当新的调查与过去的事件高度匹配（资源／症状／集群相同）时，会在上下文中注入一行 SIMILAR PAST INCIDENT (date): <root cause> 说明，并明确要求将其视为需要根据新证据核实的内容，而不是直接假定其成立。当过去的事件对诊断有实质性影响时，RCA 会引用该事件（“根因与 2026-07-03 事件相同”）。

这是对已存储摘要的检索，并非学习系统：记录是带有 TTL 的普通数据（默认 90 天，KUBENTLY_INCIDENT_TTL_SECONDS），每个租户还有数量上限（默认 200，KUBENTLY_INCIDENT_MAX_PER_NAMESPACE，超出时删除最旧的记录）。此功能默认启用；设置 KUBENTLY_INCIDENT_HISTORY=false（Helm：位于 api.env 下）可同时禁用记录和检索。

架构

• API Server：基于 FastAPI 的 REST API，用于集群管理和身份验证
• A2A Server：使用 LangGraph 实现 A2A 协议，用于工作流编排
• 测试自动化：全面的测试框架，包含 20 多个 Kubernetes 场景
• CLI 工具：现代化的 Node.js CLI，用于交互式调试

Agent 工具集

诊断 Agent 使用一小组只读工具进行调查：

• list_clusters — 列出已注册的集群
• execute_kubectl — 对单个集群执行只读 kubectl 命令（执行器会强制执行白名单）
• execute_kubectl_multi — 将一条只读 kubectl 命令分发到多个集群执行
• get_recent_changes — 查看工作负载或命名空间的“变更内容”时间线：发布（ReplicaSet 修订版本及变更原因）、Helm 发布历史（需选择启用：changeCorrelation.helmHistory.enabled）、ArgoCD 同步历史（可选：changeCorrelation.argocd.url）以及 Normal+Warning 事件，并与 RCA 中的首次错误时间戳进行关联
• get_events_for_resource — 按时间顺序列出资源及其子资源的事件（deployment → replicasets → pods）
• search_pod_logs — 根据标签选择器，在所有匹配的 Pod/容器中进行结构化日志搜索（子串或正则表达式、时间范围、支持前一个容器）。日志会在集群的执行器上过滤，因此只会返回匹配的行，并设有上限且会明确注明是否截断
• query_loki（可选）— 针对集群的 Loki 执行 LogQL 范围查询，以聚合或搜索历史日志，包括已重启或已删除 Pod 的日志。在 Helm values 中设置 loki.url 即可启用（默认未设置）；查询通过与 kubectl 命令相同的出站通道，在各集群的执行器上执行
• query_prometheus（可选）— 执行即时及范围 PromQL 查询，以获取延迟、饱和度、OOM 趋势和随时间变化的重启情况等证据。在 Helm values 中设置 prometheus.url 即可启用（默认未设置）；查询通过与 kubectl 命令相同的出站通道，在各集群的执行器上执行
• search_past_incidents — 对此部署的事件历史记录进行关键词搜索（见下文）。Redis 可用时默认启用；设置 KUBENTLY_INCIDENT_HISTORY=false 可禁用
• get_manifest_file（可选）— 只读获取已配置 GitOps 清单仓库中的文件，以便根据真实清单对建议修复进行差异比对，而非基于臆测的清单。通过 Helm values 中的 gitRemediation 启用（默认关闭）
• propose_fix_pr（可选）— 针对已配置的 GitOps 清单仓库（GitHub 或 GitLab），以拉取请求的形式提出高置信度清单修复：创建分支 → 提交 → 创建 PR，并在正文中列出调查证据，同时明确标注为机器生成。Agent 绝不会合并——由人工审核并合并，再由你的 GitOps 控制器应用。设有大小上限（文件数/变更行数）；令牌绝不会进入模型上下文，集群访问保持只读。请参阅 GitOps PR 修复
• query_cloud_logs、query_cloud_metrics、get_recent_cloud_changes（可选）— 获取集群的只读云遥测数据：AWS 上的 CloudWatch Logs Insights / CloudWatch 指标 / CloudTrail，GCP 上的 Cloud Logging / Cloud Monitoring / GKE 审计日志。执行器使用你授予其 ServiceAccount 的工作负载身份来响应（EKS Pod Identity、IRSA 或 GKE Workload Identity）——Kubently 不会存储任何云密钥，撤销 IAM 角色即可立即禁用此功能。在 Helm values 中通过 executor.cloud.enabled 按集群启用（默认关闭）；每次调用都会重新检查目标集群的执行器是否确实报告了身份。操作还受到代码级白名单的限制。请参阅 云遥测
• mcp_<server>_*（可选）— 来自外部 MCP 服务的工具（流式 HTTP，例如 Grafana Cloud 或 Datadog 的远程 MCP），通过 Helm values 中的 mcpServers 配置（默认未设置）。工具名称会加上服务名称前缀以避免冲突；结果会被视为不可信输入（进行封装并限制大小），凭据则保存在 Kubernetes Secret 中。仅连接具有只读权限的服务/凭据——Kubently 无法强制远程服务的工具遵循只读语义。请参阅 docs/MCP_CLIENT_TOOLS.md

文档

入门

• 快速入门指南 - 5 分钟内开始运行
• 入门指南 - 用于生产环境的完整设置说明
• 部署指南 - 详细的部署选项和配置

使用与运维

• CLI 管理指南 - 管理集群和执行器
• 测试查询 - API 请求示例和 A2A 协议用法
• MCP 连接指南 - 连接 MCP 客户端（Claude Desktop、Cursor、自定义 Agent）
• 环境变量 - 配置参考
• GitOps PR 修复 - Agent 提议的修复 PR（由人工合并，默认关闭）
• 云遥测 - 通过工作负载身份进行只读 CloudWatch / Cloud Logging 访问（默认关闭）
• 外部 MCP 工具 - 将第三方 MCP 服务挂载到 Agent 中，包括按请求注入

架构与开发

• 架构 - 系统设计和组件
• A2A 协议规范 - 官方协议文档
• 开发指南 - 贡献者指南

故障排除

• 入门指南 - 常见问题 - 故障排除指南

贡献

请参阅 CLAUDE.md，了解开发指南和贡献说明。

维护者

Kubently 团队 - [email protected]

许可证

Apache 2.0 许可证 - 详情请参阅 LICENSE 文件