kubently

Kubently

Kubently - エージェントによる Kubernetes のトラブルシューティング

概要

Kubently（Kubernetes + Agentically）は、無料で利用できる、セルフホスト可能、ベンダー中立のマルチクラスター Kubernetes トラブルシューティングツールです。質問を 1 つするだけで、フリート内のすべてのクラスターから AI による診断結果を並行して取得できます。直接アクセスできないクラスターも対象です。エグゼキューターは中央 API にアウトバウンド接続するため、インバウンドのイングレスも、共有 kubeconfig も、クラスターごとに配布する認証情報も必要ありません。

エージェントは A2A（Agent-to-Agent）プロトコルを介して連携します。また、どの MCP クライアント（Claude Code、Cursor、Claude Desktop）からでも、すぐに Kubently をツールとして利用できます。

主な機能

• マルチクラスターのフリートトラブルシューティング：1 つの質問を、登録済みのすべてのクラスターに並行して送信します
• アウトバウンド接続型エグゼキューター：ファイアウォールや NAT の背後にあるクラスターにも接続できます。インバウンドのイングレスも、共有 kubeconfig も不要です
• 自然言語インターフェース：会話形式で Kubernetes のトラブルシューティングとデバッグを行えます
• 包括的な分析：問題の自動検出、根本原因分析、解決策の提案を行います
• マルチ LLM 対応：Google Gemini、OpenAI、Anthropic などのプロバイダーと互換性があります
• A2A プロトコル：複雑なワークフローに対応する、業界標準のエージェント間通信です
• MCP サーバー：オプションの Model Context Protocol エンドポイントを利用すると、MCP クライアント（Claude Desktop、Cursor、カスタムエージェント）からツールに直接アクセスできます
• セキュリティ優先：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 を実行しましたか？Claude Code に Kubently を追加します。

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 の incoming 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>"]

発火したアラートはそれぞれエージェントが診断し、結果を Slack に投稿します。ノートパソコンを開く前に、ボットが根本原因を説明してくれることもよくあります。

スケジュールされたクラスター健全性ダイジェスト

アラートは事後対応です。ダイジェストはスケジュールに従って登録済みのすべてのクラスターを確認し、同じ Slack webhook に概要を 1 件投稿します。健全なクラスターは 1 行にまとめられるため、残るのは対応が必要なものだけです。

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 に伝えると、ロールアウトが落ち着くまで監視した後、実際に調査を実行します。ポッドの準備はできているか、イベントに問題はないか、新しいログにエラーはないか、デプロイ前の期間と比べてメトリクスが悪化していないか（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 が世代の変更を検知し、指示がなくてもロールアウトを検証します。

スケジュールされたチェック（定期的に確認したい質問を cron で実行）

ダイジェストでは幅広い質問を 1 つ尋ねます。スケジュールされたチェックでは、独自の質問を任意のスケジュールで尋ねられます。各チェックは、名前付きのプロンプトと cron スケジュール、および省略可能な対象クラスターで構成され、エージェントが実行して 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 を設定しないと、エージェントは起動しません。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 シークレットから取得し、LLM_PROVIDER は api.env の下に設定します。

Helm によるデプロイ

Helm values を使ってデプロイをカスタマイズします。

Kubently は単一のチャートとして提供されます。コンポーネントは api.enabled、redis.enabled、executor.enabled で有効化・無効化できます。リモートクラスターに executor のみをインストールする場合も、最初の 2 つを無効にした同じチャートを使用します。

# 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 は必須で、チャートのデフォルト値はありません。api.env の下に設定してください（anthropic-claude、openai、または google-gemini）。設定項目の全容についてはENVIRONMENT_VARIABLES.mdを、本番環境へのデプロイ手順についてはGETTING_STARTED.mdをご覧ください。

オペレーター向けランブック

組織内で共有されている知見を調査に活用できます。ランブックは、簡易的なフロントマターを含む手書きの Markdown ファイルです。調査（チャットでの質問、Alertmanager アラート、または A2A 呼び出し）がランブックの条件に一致すると、エージェントはそれを「この状況におけるオペレーターのランブック」として受け取り、該当する箇所に従い、逸脱があれば記録し、診断でランブック名を引用します。

実例：

---
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 ポッドにマウントされる ConfigMap になり、ポッドを再起動しなくても編集内容が反映されます）。

# 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 文字）があります。多数のランブックの断片よりも、最もよく一致するランブックを丸ごと 1 つ使う方が優先されます。Helm を使わない場合は、KUBENTLY_RUNBOOKS_DIR に任意の .md ファイルを含むディレクトリを指定してください。

インシデント履歴

過去の診断を検索可能な組織の記憶として活用できます。調査で根本原因が特定されると、Kubently は日付、クラスター、関連リソース、症状のキーワード、根本原因を一文でまとめた説明、明示されている場合は解決策を簡潔な記録として Redis に保存します。記録は認証済みの呼び出し元ごとに分離されます（会話メモリーと同じ名前空間の境界を使用するため、マルチテナント環境では、あるテナントのインシデントが別のテナントから見えることはありません）。

履歴は次の 2 つの方法で使用されます。

• エージェントの 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 サーバー：クラスター管理と認証のための FastAPI ベースの REST API
• A2A サーバー：ワークフローのオーケストレーションに LangGraph を使用した A2A プロトコルの実装
• テスト自動化：20 件以上の Kubernetes シナリオを含む包括的なテストフレームワーク
• CLI ツール：対話型デバッグのための最新の Node.js CLI

エージェントのツールセット

診断エージェントは、少数の読み取り専用ツールを使って調査します。

• list_clusters — 登録済みクラスタを列挙します
• execute_kubectl — 1 つのクラスタに対して読み取り専用の kubectl を実行します（実行環境で許可リストを強制します）
• execute_kubectl_multi — 1 つの読み取り専用 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 — ラベルセレクターに一致するすべてのポッド／コンテナを対象に、構造化ログを検索します（部分文字列または正規表現、時間範囲、以前のコンテナのサポート）。ログはクラスタの実行環境でフィルタリングされるため、一致した行のみが返されます。件数には上限があり、切り捨てがあった場合は明示されます
• query_loki (任意) — クラスタの Loki に対する LogQL の範囲クエリです。再起動または削除されたポッドのログを含む、集計済み／過去のログ検索に利用できます。Helm values で loki.url を設定すると有効になります（デフォルトでは未設定）。クエリは kubectl コマンドと同じアウトバウンドチャネルを通じて、各クラスタの実行環境で実行されます
• query_prometheus (任意) — レイテンシ、飽和度、OOM の傾向、時間経過に伴う再起動状況の証拠を取得する、即時および範囲指定の PromQL クエリです。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 の作成まで行います。本文には機械による提案であることが明記されます。エージェントが マージすることはありません。人がレビューしてマージし、GitOps コントローラーが適用します。サイズ（ファイル数／変更行数）に上限があり、トークンがモデルのコンテキストに入ることはなく、クラスタへのアクセスは読み取り専用のままです。GitOps PR Remediation を参照してください
• query_cloud_logs、query_cloud_metrics、get_recent_cloud_changes (任意) — クラスタの読み取り専用クラウドテレメトリです。AWS では CloudWatch Logs Insights／CloudWatch メトリクス／CloudTrail、GCP では Cloud Logging／Cloud Monitoring／GKE 監査ログを利用します。実行環境は、ServiceAccount に お客様が 付与したワークロード ID（EKS Pod Identity、IRSA、または GKE Workload Identity）を使用して応答します。Kubently がクラウドキーを保存することはなく、IAM ロールを取り消すと、この機能は即座に無効になります。Helm values の executor.cloud.enabled でクラスタごとに有効にします（デフォルトでは無効）。各呼び出し時に、対象クラスタの実行環境が実際に ID を報告していることを再確認します。さらに、操作はコードレベルの許可リストによって制限されます。Cloud Telemetry を参照してください
• mcp_<server>_* (任意) — Helm values の mcpServers で設定した外部 MCP サーバー（Grafana Cloud や Datadog のリモート MCP など、ストリーミング可能な HTTP）のツールです（デフォルトでは未設定）。ツール名には衝突を避けるためサーバー名がプレフィックスとして付与されます。結果は信頼できない入力として扱われ（フレーミングを適用し、サイズを制限）、認証情報は Kubernetes シークレットに保存されます。読み取り専用のスコープを持つサーバー／認証情報のみを接続してください。Kubently はリモートサーバーのツールに読み取り専用の動作を強制できません。docs/MCP_CLIENT_TOOLS.md を参照してください

ドキュメント

はじめに

• クイックスタートガイド - 5 分で使い始められます
• はじめに - 本番環境で使用するための完全なセットアップ手順
• デプロイガイド - デプロイオプションと設定の詳細

使用方法と運用

• CLI 管理者ガイド - クラスターとエグゼキューターの管理
• テストクエリ - API リクエストの例と A2A プロトコルの使用方法
• MCP 接続ガイド - MCP クライアント（Claude Desktop、Cursor、カスタムエージェント）の接続
• 環境変数 - 設定リファレンス
• GitOps PR の修正対応 - エージェントが提案する修正 PR（人間がマージ。デフォルトでは無効）
• クラウドテレメトリ - ワークロード ID による読み取り専用の CloudWatch / Cloud Logging アクセス（デフォルトでは無効）
• 外部 MCP ツール - リクエストごとの注入を含む、サードパーティ製 MCP サーバーのエージェントへのマウント

アーキテクチャと開発

• アーキテクチャ - システム設計とコンポーネント
• A2A プロトコル仕様 - 公式プロトコルドキュメント
• 開発ガイド - コントリビューター向けガイドライン

トラブルシューティング

• はじめに - よくある問題 - トラブルシューティングガイド

コントリビューション

開発ガイドラインとコントリビューションの手順については、CLAUDE.md を参照してください。

メンテナー

Kubently Team - [email protected]

ライセンス

Apache 2.0 ライセンス - 詳細は LICENSE ファイルを参照してください