
Kubently
io.github.kubently由 GitHub 账号 kubently 发布v2.3.1更新于 Oct 24, 2026
Troubleshoot Kubernetes agentically: natural-language cluster diagnosis via ask_kubently
概览
Kubently 是自托管的 Kubernetes 故障排查服务,让助手通过 ask_kubently 工具用自然语言诊断集群。
- 可以做什么
- 针对一个或多个已注册的 Kubernetes 集群提出诊断问题,获得 AI 诊断答案,一个问题可并行分发到整个集群群组。使用只读 kubectl 检查集群与资源、列出集群,并获取工作负载和命名空间的事件与近期变更时间线。按标签选择器跨 Pod 和容器搜索日志,可选查询 Loki 与 Prometheus 获取历史日志和指标。检索 Redis 中保存的历史事件,并在排查中引用运维手册。可选地针对 GitOps 仓库以拉取请求形式提出清单修复,配置后还可使用只读云遥测和外部 MCP 工具。
- 适用场景
- 适合运行一个或多个 Kubernetes 集群、希望助手自动排查崩溃循环、发布失败、资源压力或告警事件的场景,无需手动执行 kubectl。也适合需要定期集群健康检查、部署验证或事件记忆的团队。
- 运行要求
- 以本地 npm CLI 包通过 npx 运行,但依赖可从客户端访问的自托管 Kubently 部署(Helm 安装、API 服务器、执行器、Redis)。必须通过 LLM_PROVIDER 选择模型提供商,并提供对应密钥,如 ANTHROPIC_API_KEY、OPENAI_API_KEY 或 GOOGLE_API_KEY。HTTP 连接使用 X-API-Key 请求头。可选的 Loki、Prometheus、GitOps 和云遥测集成需另行配置。
安装
在 SourceWeft 中
- 打开 控制台中的 Kubently,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
Kubently
[License] [Python] [Kubernetes] [A2A Protocol] [Docker] [Helm] [Security Policy] [Contributing]
Kubently - Troubleshooting Kubernetes Agentically
Overview
Kubently (Kubernetes + Agentically) is a free, self-hosted, vendor-neutral multi-cluster Kubernetes troubleshooter. Ask one question, get AI-diagnosed answers from every cluster in your fleet in parallel — including clusters you can't reach directly: executors dial outbound to the central API, so there's no inbound ingress, no shared kubeconfig, and no per-cluster credentials to distribute.
Agents collaborate over the A2A (Agent-to-Agent) protocol, and any MCP client (Claude Code, Cursor, Claude Desktop) can use Kubently as a tool out of the box.
Key Features
- Multi-Cluster Fleet Troubleshooting: One question fans out across all registered clusters in parallel
- Outbound-Dial Executors: Reach clusters behind firewalls/NAT — no inbound ingress, no shared kubeconfig
- Natural Language Interface: Conversational Kubernetes troubleshooting and debugging
- Comprehensive Analysis: Automated issue detection, root cause analysis, and solution recommendations
- Multi-LLM Support: Compatible with Google Gemini, OpenAI, Anthropic, and other providers
- A2A Protocol: Industry-standard agent-to-agent communication for complex workflows
- MCP Server: Optional Model Context Protocol endpoint so MCP clients (Claude Desktop, Cursor, custom agents) get direct tool access
- Security-First: API key authentication, OAuth/OIDC support, and TLS with cert-manager
- Persistent Sessions: Redis-backed conversation history and context management
- Extensive Tool Suite: kubectl integration, log analysis, resource inspection, and more
Quick Start
For Users: Get Started in 5 Minutes
Point kubectl at any cluster (kind, minikube, or real) and run:
That's it. The CLI installs Kubently via Helm, wires up secrets and the executor, port-forwards the API, and drops you into a debug chat:
You'll need an LLM API key (Anthropic, OpenAI, or Google) — the installer
prompts for it, or reads ANTHROPIC_API_KEY / OPENAI_API_KEY /
GOOGLE_API_KEY from your environment. Use --provider to pick the LLM,
--chart ./deployment/helm/kubently to install from a local checkout, and
kubently install --help for everything else.
Use from Claude Code / Cursor (MCP)
Already ran kubently install? Add Kubently to Claude Code:
Or connect directly over HTTP (no bridge process):
Then ask Claude things like "use kubently to figure out why payments pods are crashlooping". Any MCP client works — see docs/MCP.md for Cursor and generic configuration.
Proactive diagnosis (Alertmanager → Slack)
Set api.env.SLACK_WEBHOOK_URL to a Slack incoming-webhook URL and point
Alertmanager at Kubently:
Each firing alert is diagnosed by the agent and the result is posted to Slack — the bot often explains the root cause before you've opened your laptop.
Scheduled fleet health digest
Alerts are reactive. A digest sweeps every registered cluster on a schedule and posts one summary to the same Slack webhook — healthy clusters collapse to a single line, so what's left is what needs you.
Preview it before you schedule it — dry_run returns the digest and posts
nothing:
The digest question is yours to change. Pass query in that request to try one
immediately, then keep the wording you like via fleetReport.query in values:
To run the real scheduled path once — image, secrets, in-cluster URL and all:
Deployment verification (did that deploy actually work?)
Tell Kubently what you just deployed and it watches the rollout settle, then runs a real investigation — pods ready? events clean? errors in the new logs? metrics regressed vs the pre-deploy window (when Prometheus is configured)? — and posts a PASS/FAIL verdict with the evidence to Slack. Wire it into the last step of your CI pipeline:
Add "dry_run": true to get the verdict back synchronously without posting.
No CI access? Label the workload instead — kubently.io/verify=enabled — and
enable verifyDeployment.watch in values: Kubently notices every generation
change and verifies the rollout unprompted.
Scheduled checks (your recurring questions, on cron)
The digest asks one broad question. Scheduled checks let you ask your questions on their schedules — each check is a named prompt with a cron schedule and optional target clusters, run by the agent and posted to Slack:
A passing check posts nothing — silence means green (set notifyOnPass: true to hear about passes too). Failures always post, evidence included.
Iterate on a check without waiting for cron:
📖 See QUICK_START.md for full quick-start guide
📚 See GETTING_STARTED.md for production deployment
For Developers: Local Testing
📖 See CLAUDE.md for development guidelines
Configuration
LLM Providers
Pick a provider with LLM_PROVIDER and supply that provider's key. There is
no default provider — the agent refuses to start without LLM_PROVIDER. For
local development with deployment/docker-compose.yaml, put both in .env
(see deployment/.env.example):
In Kubernetes the keys come from the kubently-llm-secrets secret and
LLM_PROVIDER goes under api.env.
Helm Deployment
Customize deployment using Helm values:
Kubently ships as a single chart. Its components are switched on and off with
api.enabled, redis.enabled and executor.enabled — an executor-only
install on a remote cluster is the same chart with the first two disabled.
LLM_PROVIDER is required and has no chart default — set it under api.env
(anthropic-claude, openai, or google-gemini). See
ENVIRONMENT_VARIABLES.md for the full
configuration surface, and GETTING_STARTED.md for
the production walkthrough.
Operator Runbooks
Feed your organization's tribal knowledge into investigations. Runbooks are hand-written markdown files with lightweight frontmatter; when an investigation (a chat question, an Alertmanager alert, or an A2A call) matches a runbook's criteria, the agent receives it as "the operator's runbook for this situation", follows it where applicable, notes deviations, and cites it by name in the diagnosis.
A worked example:
Deploy runbooks as Helm values (they become a ConfigMap mounted into the API pod; edits go live without a pod restart):
Matching is scored: an alert-name hit outranks namespace/workload selector
hits, which outrank topic hits. The best match is injected first, and the
total injected size is capped (KUBENTLY_RUNBOOKS_MAX_CHARS, default 8000
characters) — one complete, best-matching runbook beats fragments of many.
Outside Helm, point KUBENTLY_RUNBOOKS_DIR at any directory of .md files.
Incident History
Past diagnoses become searchable institutional memory. Whenever an investigation concludes with a root cause, Kubently stores a compact record — date, cluster, resources involved, symptom keywords, the root-cause one-liner, and the resolution when one was stated — in Redis, isolated per authenticated caller (the same namespace boundary as conversation memory, so in multi-tenant deployments one tenant's incidents are never visible to another).
The history is used two ways:
- The agent's
search_past_incidentstool answers "have we seen this before?" — keyword search over resources, clusters, symptoms and root-cause text, newest first. - Auto-surface: when a new investigation strongly matches a past incident
(same resources/symptoms/cluster), a one-line
SIMILAR PAST INCIDENT (date): <root cause>note is injected into context — framed as something to verify against fresh evidence, never to assume. When a past incident materially informs the diagnosis, the RCA cites it ("same root cause as the 2026-07-03 incident").
This is retrieval over stored summaries, not a learning system: records are
plain data with a TTL (default 90 days, KUBENTLY_INCIDENT_TTL_SECONDS) and
a per-tenant cap (default 200, KUBENTLY_INCIDENT_MAX_PER_NAMESPACE,
oldest evicted). The feature is on by default; set
KUBENTLY_INCIDENT_HISTORY=false (Helm: under api.env) to disable both
recording and retrieval.
Architecture
- API Server: FastAPI-based REST API for cluster management and authentication
- A2A Server: Implements A2A protocol with LangGraph for workflow orchestration
- Test Automation: Comprehensive testing framework with 20+ Kubernetes scenarios
- CLI Tools: Modern Node.js CLI for interactive debugging
Agent Toolset
The diagnostic agent investigates with a small set of read-only tools:
list_clusters— enumerate registered clustersexecute_kubectl— read-only kubectl against one cluster (whitelist-enforced on the executor)execute_kubectl_multi— one read-only kubectl command fanned out across many clustersget_recent_changes— "what changed?" timeline for a workload or namespace: rollouts (ReplicaSet revisions + change-causes), Helm release history (opt-in:changeCorrelation.helmHistory.enabled), ArgoCD sync history (optional:changeCorrelation.argocd.url), and Normal+Warning events — correlated against first-error timestamps in the RCAget_events_for_resource— chronological events for a resource and its children (deployment → replicasets → pods)search_pod_logs— structured log search across every pod/container matching a label selector (substring or regex, time bounds, previous-container support). Logs are filtered on the cluster's executor so only matching lines — capped, with explicit truncation notes — come backquery_loki(optional) — LogQL range queries against a cluster's Loki for aggregated/historical log search, including logs from pods that have restarted or been deleted. Enabled by settingloki.urlin Helm values (unset by default); queries execute on each cluster's executor through the same outbound channel as kubectl commandsquery_prometheus(optional) — instant and range PromQL queries for latency, saturation, OOM-trend and restarts-over-time evidence. Enabled by settingprometheus.urlin Helm values (unset by default); queries execute on each cluster's executor through the same outbound channel as kubectl commandssearch_past_incidents— keyword search over this deployment's incident history (see below). On by default when Redis is available; disable withKUBENTLY_INCIDENT_HISTORY=falseget_manifest_file(optional) — read-only fetch of a file from the configured GitOps manifests repo, so proposed fixes are diffed against the real manifest instead of a hallucinated one. Enabled withgitRemediationin Helm values (off by default)propose_fix_pr(optional) — proposes a high-confidence manifest fix as a pull request against the configured GitOps manifests repo (GitHub or GitLab): branch → commit → PR with the investigation evidence in a body clearly marked machine-proposed. The agent never merges — a human reviews and merges, and your GitOps controller applies. Size-capped (files/changed lines), token never enters model context, cluster access stays read-only. See GitOps PR Remediationquery_cloud_logs,query_cloud_metrics,get_recent_cloud_changes(optional) — read-only cloud telemetry for a cluster: CloudWatch Logs Insights / CloudWatch metrics / CloudTrail on AWS, Cloud Logging / Cloud Monitoring / GKE audit logs on GCP. The executor answers them using the workload identity you grant its ServiceAccount (EKS Pod Identity, IRSA, or GKE Workload Identity) — no cloud key is ever stored by Kubently, and revoking the IAM role kills the capability instantly. Enabled per cluster withexecutor.cloud.enabledin Helm values (off by default); each call re-checks that the target cluster's executor actually reports an identity. Operations are additionally limited by a code-level allowlist. See Cloud Telemetrymcp_<server>_*(optional) — tools from external MCP servers (streamable HTTP, e.g. Grafana Cloud's or Datadog's remote MCP) configured viamcpServersin Helm values (unset by default). Tool names are prefixed with the server name to avoid collisions; results are treated as untrusted input (framed and size-capped) and credentials stay in Kubernetes secrets. Connect read-scoped servers/credentials only — Kubently cannot enforce read-only semantics on a remote server's tools. Seedocs/MCP_CLIENT_TOOLS.md
Documentation
Getting Started
- Quick Start Guide - Get running in 5 minutes
- Getting Started - Complete setup for production use
- Deployment Guide - Detailed deployment options and configuration
Usage & Operations
- CLI Admin Guide - Managing clusters and executors
- Test Queries - Example API requests and A2A protocol usage
- MCP Connect Guide - Connect MCP clients (Claude Desktop, Cursor, custom agents)
- Environment Variables - Configuration reference
- GitOps PR Remediation - Agent-proposed fix PRs (human-merged, default off)
- Cloud Telemetry - Read-only CloudWatch / Cloud Logging access via workload identity (default off)
- External MCP Tools - Mounting third-party MCP servers into the agent, including per-request injection
Architecture & Development
- Architecture - System design and components
- A2A Protocol Spec - Official protocol documentation
- Development Guide - Guidelines for contributors
Troubleshooting
- Getting Started - Common Issues - Troubleshooting guide
Contributing
See CLAUDE.md for development guidelines and contribution instructions.
Maintainer
Kubently Team - [email protected]
License
Apache 2.0 License - See LICENSE file for details
来源:README.md,提交 06053a7
工具
0版本历史
1- v2.3.1最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分