🤖 AI-Powered Kubernetes Assistant with MCP

Kubernetes Diagnostic MCP

Next.js で構築された、読み取り専用の Kubernetes インシデントトリアージプラットフォームです。公式の Kubernetes JavaScript クライアントを通じてクラスターのライブ状態を収集し、決定論的なルールエンジンで検出事項を提示します。また、オプションで AI を活用したインシデントの説明を生成できます。クラスターへの書き込みは一切行いません。

インストール： セルフホスティング、OIDC／Keycloak、テナント分離、Helm。

このバージョンでは、明示的なテナント設定と認証済みアクセスが必要です。環境に応じたクラスター認証情報は使用せず、従来の共有履歴も自動的にインポートしません。

---

機能

調査と復旧のワークフロー

• Pod のトラフィック経路 — 設定済みの Ingress → Service → EndpointSlice → Pod の経路、ポートマッピング、バックエンドの状態、Ingress／Egress の NetworkPolicy による分離を調査します。Pod のネットワーキングと権限設定を参照してください。パケットレベルのフローテレメトリは収集しません。
• 過去の調査 — 保持されたイベントとスナップショットからインシデントのタイムラインを再構成し、現在の障害エピソードの範囲を特定して、証拠へのリンクと確認チェックを用いて確信度の低い調査の手掛かりを順位付けします。オプションで、テナント認証済みの Helm CronJobs がインシデント発生前にデータを収集します。過去の調査を参照してください。
• 何が変わったか？ — 範囲を指定したスナップショットを比較し、デプロイのリビジョン、イメージ、リソース設定、構成のフィンガープリント、サービスのルーティング変更、オプションの Prometheus CPU／メモリの証拠を確認します。相関関係には仮説であることが示されます。
• 関連するインシデント — オーナー参照、サービスセレクター、正常でないノードへの配置、障害が発生している PVC 依存関係を用いて検出事項をグループ化し、各リンクの証拠を提示します。
• 修正して検証 — 観測された正常なベースラインへの、サポート対象の Deployment のロールバックを提案し、固定された GitOps マニフェストの変更をプレビューして、レビュー済みの GitHub PR を作成し、マージ後に復旧が継続していることを検証します。
• 永続的な履歴 — アトミックなディスクストレージを使用し、修正ワークフロー向けにベースラインと検証の証拠を保持します。

GitHub の対象、オプションの Prometheus、永続ストレージ、API の例、復旧に関する契約については、調査ワークフローの設定と制限事項を参照してください。

診断対象

リソース	検出される障害モード
Pods	CrashLoopBackOff、ImagePullBackOff、OOMKilled、スケジューリングの失敗、プローブの失敗
Workloads	Deployment、StatefulSet、DaemonSet、ReplicaSet、Job が望ましい状態ではない
Services	セレクターが正常なエンドポイントを 0 件に解決する
Nodes	NotReady、MemoryPressure、DiskPressure、PIDPressure、cordoned
HPAs	スケーリングできない（AbleToScale=False）、最大レプリカ数に達している
PVCs	Pending（プロビジョナーの障害）、Lost（バックエンドの PV が消失）
CronJobs	スケジュールを逃したまま停止しているジョブ
Events	すべてのリソースタイプにわたる、相関のある警告イベント

構造化されたリスクと影響のモデル

すべての検出事項には、プレーンテキストの説明に加えて、次の 2 つの構造化された評価が含まれます。

• ImpactAssessment — 範囲（pod／workload／service／namespace／node／cluster）、影響を受けるリソースの参照、影響を受けるレプリカ数、問題がユーザーに影響するかどうか、概要文
• RiskAssessment — リスクレベル、確信度、影響範囲、放置した場合のリスク、修正した場合のリスク、評価の根拠

このモデルはサマリーの主要なリスク一覧を支え、UI が Markdown を解析せずに構造化されたコンテキストを表示できるようにします。

自然言語クエリモード

エンジニアはフォームのフィールドに入力する代わりに、平易な英語でインシデントを説明できます。

「直近のデプロイ以降、checkout ポッドがクラッシュし続けています」

LLM は説明から診断の意図（名前空間、ワークロード、重点領域、症状）を抽出し、稼働中のクラスターのインベントリと照合して検証したうえで、具体的な DiagnosticScope に解決します。その後、決定論的エンジンは変更なく実行されます。LLM の役割は入力の変換のみであり、所見を生成することはありません。

主な動作：

• 曖昧さの解消 — ワークロードが複数の名前空間に存在する場合、確認パネルでエンジニアが実行前に選択できます
• 名前空間の推定 — ワークロード名から名前空間を一意に特定できる場合、自動的に推定されます（確認手順あり）
• 安全性チェック — 診断を呼び出す前に、抽出した名前空間名とワークロード名を実際のクラスターと照合して検証します
• 編集へのフォールバック — 「編集」ボタンを押すと、解決した値がフォームモードに入力されるため、エンジニアは解釈を修正できます
• 適切な機能縮退 — LLM キーが設定されていない場合、クエリモードは自動的に無効になります

AI インシデントのナラティブ

GROQ_API_KEY または OPENAI_API_KEY が設定され、AI 要約が有効な場合、決定論的な所見と Markdown レポートが LLM に渡され、次の内容が生成されます。

• エグゼクティブサマリー
• 根拠の引用を含む、考えられる根本原因
• 次のアクション
• 読み取り専用の自動化コマンド

決定論的レポートは先に返されます。ダッシュボードは任意のナラティブを別途リクエストするため、プロバイダーの応答遅延によって根拠の提示が遅れることはありません。AI ナラティブは、レポートセクションに書式付き Markdown として表示されます。LLM にはリソース、コマンド、原因を捏造しないよう指示されており、決定論的エンジンがすでに見つけた内容の説明と優先順位付けのみを行えます。このツールは LLM キーがなくても完全に機能します。

LLM の優先順位： GROQ_API_KEY が設定されている場合は Groq（llama-3.3-70b-versatile）を使用します。設定されていない場合は OpenAI（gpt-4o-mini）をフォールバックとして使用します。

UI

• フォーム／クエリ切り替え — 構造化フォーム入力と自然言語クエリモードを切り替えます。設定は localStorage に保存されます
• 名前空間ドロップダウン — 稼働中のクラスターから自動的に値が入力されます。クラスターに接続できない場合は、テキスト入力に切り替わります
• ワークロードドロップダウン — 名前空間が変更されると自動的に更新されます
• クラスターコンテキストセレクター — 再起動せずに kubeconfig コンテキストを切り替えます
• 診断実行履歴 — 最近保存された実行結果がサイドバーに表示されます。項目をクリックすると、全結果を再読み込みできます
• メトリクスタイル — ポッド数、異常なポッド、警告イベント、ノードの健全性、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 プローブで使用）

認証と分離

• Keycloak のセットアップガイドが付属した汎用 OIDC サインイン。認可コード、PKCE、state、nonce、および署名済み ID トークンの検証に対応します。
• viewer/operator/admin ロールを持つテナントワークスペース。Kubernetes 認証情報は分離され、許可する名前空間をリストで指定します。
• 履歴、ベースライン、修正計画、インテグレーション設定はテナントごとに分離されます。
• 自動化用のテナント API キー。共有のグローバルキーや匿名アクセスはありません。
• ID ごとおよびテナントごとのレート制限、同時収集数の制限、Kubernetes 読み取りのページネーション、タイムアウトを適用します。
• PVC、読み取り専用の認証情報マウント、Ingress ポリシー、個別の readiness/liveness チェックを備えた非 root の Helm デプロイメント。

インストールまたは開発

インストールガイドに従って、テナント認証情報のプロビジョニング、OIDC プロバイダーの設定、Secret の作成、同梱の Helm チャートのインストールを行います。ソースリポジトリからダウンロードし、ご自身のレジストリでイメージをビルドしてください。リリースやイメージは自動公開されません。

ローカル開発では、.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 チャートも検証します。

環境変数

変数	用途
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 の例を出発点としてください。アプリケーションのサービスアカウントにはクラスター全体の権限がなく、トークンも自動マウントされません。ノードへのアクセスには、テナントに明示的な機能を付与し、さらにクラスター レベルの権限を設定する必要があります。

認証情報のローテーション、分離の確認、ストレージの制限、共有履歴からの移行、共有ホスティングのロードマップについては、セルフホストガイドを参照してください。