K8gentS — Kubernetes RCA MCP Server

K8gentS ☸️🤖

Kubernetes 向け Human-in-the-Loop RCA エージェント — LLM による診断と、OPA による制限付きの修復

---

📖 概要

K8gentS は、単一の前提に基づいて構築された Kubernetes 診断エージェントです。LLM はクラスターの障害について 推論 するには適していますが、監視なしで 対処 するには適していません。クラスターのイベントストリームを継続的に監視し、Warning クラスのイベントを Gemini を活用した 根本原因分析（RCA） パイプラインで処理して、上位の仮説と解決手順を Slack に提示します。すべての修復は Human-in-the-Loop（HITL） で行われます。何かを変更する前に、レビュー担当者がインタラクティブなボタンで承認または却下します。承認された修正は、一時的な Job 内で実行され、その影響範囲は RBAC とは独立した、API サーバー上の OPA Gatekeeper アドミッションポリシーによって制限されます。推論は設計上、非決定的ですが、その周囲の制御はそうではありません。

目標は、LLM に kubectl apply を任せることなく、診断可能な障害の MTTR を短縮することです。

---

🧠 難しい課題

Kubernetes 側を構築することは簡単です。本当の課題は、その根幹にあるエンジンが本質的に非決定的である場合に、診断レイヤーの信頼性を確保することです。

従来の可観測性は、保証を前提に構築されています。既知のしきい値に達するとアラートが発報します。ダッシュボードには再現性のある数値が表示されます。ログは同じクエリに対して一貫した回答を返します。SRE の成功は、この予測可能性にかかっています。それがインシデント対応を繰り返し実行可能にし、オンコールを持続可能にするのです。

LLM 主導の診断レイヤーは、その前提を崩します。同じ Pod の障害でも、3 回の異なる実行で、もっともらしい説明が 3 通り生成されることがあります。それぞれに筋は通っているかもしれません。前提が異なれば、それぞれが正しいことさえあります。しかし、「もっともらしい」は「正しい」と同じではありません。インフラストラクチャでは、その隔たりが障害の発生する場所です。

K8gentS の構築を通じて取り組んでいる、具体的な課題をいくつか紹介します。

1. 出力空間に上限がない場合の信頼度スコアリング。 エージェントは信頼度指標とともに根本原因の上位 3 件を返しますが、いったい何に対する信頼度なのでしょうか。モデルは既知の障害モードの固定セットから選んでいるわけではなく、自由形式の仮説を生成しています。信頼度スコアを適切に較正するには参照分布が必要ですが、ここでの分布は、その実行でモデルがたまたま生成したものです。

2. 推論を信頼するタイミングと、決定論的なチェックに切り替えるタイミング。― ここが腕の見せどころです CrashLoopBackOff や OOMKilled などの障害には、確立された診断手順があり、決定論的なチェックなら毎回正しい結果を得られます。一方で、信号を横断して推論するモデルの能力が役立つケースもあります。その境界を見極めること、しかも実行時に判断することは容易ではなく、ここにこそ真の腕の見せどころがあります。

3. 想定していなかった障害を見つけるエージェントの評価。 標準的な ML の評価手法は、「正解」がどのようなものかを把握していることを前提とします。診断エージェントの価値の一部は、新しい障害モードを検知することにあります。定義上、それは事前に列挙できなかった障害です。では、何が誤りで何が正しいのかを、どう判断すればよいのでしょうか。

4. 「クラスター内のツール」という問題。 監視するものを、どう監視すればよいのでしょうか。現在、このサービスはクラスター内でサービスとして実行されるように設定されています。しかし、サービス自体がリソースを枯渇させたり、サービス自体に障害が発生したりした場合はどうなるでしょうか。サービス自体が問題の原因かどうかを、どう特定すればよいのでしょうか。

5. この問題に適したモデルの見極め。 ほかにもさまざまな種類の機械学習モデルがある中で、非決定的な大規模言語モデルは本当に適切な選択なのでしょうか。それとも、インフラストラクチャ関連の問題には別のモデルのほうが適しているのでしょうか。

これらは、現在まさに取り組んでいる課題です。いずれかを解決したことがある方、あるいは私よりも明快な整理の仕方をお持ちの方は、ぜひお聞かせください。

---

✨ 主な責務

1. 継続的な監視： クラスターを監視し、エラーイベント、クラッシュした Pod、CrashLoopBackOff 状態、OOMKilled イベントのほか、Connectivity/DNS、Database Deadlock、Secret/Config Missing などの障害条件を検知します。
2. 自動根本原因分析（RCA）： 異常を検知すると、関連するコンテキスト（最近のログ、Pod の説明、イベント履歴）を安全に取得し、シークレットや個人を特定できる情報（PII）を除去してから、このコンテキストを LLM ベースの推論エンジンに送信します。
3. 通知と信頼度スコア： Socket Mode を介して、指定した Slack チャンネルに次の内容を通知します。
   • エラーの詳細な概要。
   • 信頼度指標を添えた、根本原因の候補トップ 3。
   • 段階的な解決手順。
4. 対話型の修復（オプトイン）： Slack 上でインタラクティブなボタンを使い、ユーザーに直接確認を求めます。ボタンは 「修正を承認」 または 「手動で対応します」 です。
   • デフォルトの設定 — 読み取り専用： エージェントは厳密に読み取り専用であり、デフォルトで非常に高いセキュリティを確保します。

---

🛠️ アーキテクチャとセキュリティ

このエージェントでは、各レイヤーが独立して影響範囲を制限します。これは単なる冗長性のためではなく、推論エンジンが非決定論的である場合、単一の制御だけでは不十分だからです。

レイヤー	仕組み	防止するもの
Pod のセキュリティ	runAsNonRoot、読み取り専用ファイルシステム、すべての Linux ケイパビリティを削除	コンテナの脱出、権限昇格
RBAC	エージェント Pod は厳密に読み取り専用。書き込み動詞を持つのは k8gent-executor-sa のみ	エージェントの侵害によるクラスターの変更
一時的なエグゼキューター	k8gent-executor-sa を介した短命な Job。ttlSecondsAfterFinished=120	修復後に永続的な足掛かりが残ること
OPA Gatekeeper	API サーバーのアドミッションレイヤーで Rego ポリシーを適用	RBAC の設定ミスがあっても、エグゼキューターが許可範囲を逸脱すること
ログのサニタイズ	正規表現のスイーパーが LLM 呼び出しの前に IP、JWT、API キー、メールアドレスを除去	LLM プロンプトを介したシークレットの流出
レート制限	1 時間ごとのサーキットブレーカーとイベントのデバウンス	ノイズによる API 利用枠の枯渇
Ingress を使わない通信	Slack Socket Mode。公開エンドポイントや Ingress ルールなし	インバウンド攻撃対象領域

deploy/helm/k8gents/templates/opa-gatekeeper/ に定義されている OPA Gatekeeper ポリシーは、エグゼキューターのサービスアカウントが serviceAccountName を変更すること、hostNetwork または hostPID を有効にすること、kube-system 内で動作すること、Pod と Deployment 以外のリソース種別を変更することを明示的に禁止します。この制約は RBAC とは独立して、Kubernetes API のアドミッションレイヤーで直接適用されます。

---

🚀 デプロイ

K8gentS は Helm チャートとして提供されます。OPA Gatekeeper はチャートの依存関係として宣言されており、セキュリティサンドボックスはエージェントとともに自動的にインストールされます。

前提条件

• Kubernetes v1.20 以降、Helm 3
• 対象クラスターに認証済みの kubectl
• Google Gemini API キー（AI_API_KEY）
• Socket Mode を有効にした Slack アプリ（xoxb- で始まる SLACK_BOT_TOKEN と、xapp- で始まる SLACK_APP_TOKEN が生成されます）
• Slack チャンネル ID（SLACK_CHANNEL_ID）と、承認者の Slack ユーザー ID をカンマ区切りで並べたリスト（ALLOWED_APPROVERS）

1. Slack の設定

1. api.slack.com で Slack アプリを作成します。
2. Socket Mode を有効にします → アプリレベルのトークン（xapp-...）が生成されます。
3. インタラクティブコンポーネントを有効にします。
4. chat:write と chat:write.public の OAuth スコープを追加します → ボットトークン（xoxb-...）が生成されます。
5. ボットをアラート用チャンネルに招待し、チャンネル設定からチャンネル ID をコピーします。

2. エージェントイメージのビルドとプッシュ

docker build -t your-registry/k8gent:latest .
docker push your-registry/k8gent:latest

deploy/helm/k8gents/values.yaml の image.repository を、使用するレジストリのパスに合わせて更新します。

3. Helm によるインストール

# Fetch chart dependencies (downloads OPA Gatekeeper)
helm dependency update deploy/helm/k8gents

# Install — secrets are injected at deploy time, never stored in source
helm install k8gents deploy/helm/k8gents \
  --namespace k8gent-system \
  --create-namespace \
  --set secrets.aiApiKey="YOUR_GEMINI_KEY" \
  --set secrets.slackBotToken="xoxb-..." \
  --set secrets.slackAppToken="xapp-..." \
  --set secrets.slackChannelId="C12345678" \
  --set secrets.allowedApprovers="U123456,U789012"

OPA サンドボックスを無効にする場合（クラスターですでに独自のポリシーを設定した Gatekeeper が稼働している場合）：

--set sandbox.enabled=false --set gatekeeper.enabled=false

4. インストールの確認

kubectl logs -l app=k8gents -n k8gent-system -f

Watcher がクラスター API に接続し、Slack Socket Mode の接続が初期化されることを確認できます。

---

⚙️ 設定

主な環境変数（Helm では --set agent.* で設定します。ローカルで実行する場合は直接設定できます）：

変数	デフォルト	説明
WATCH_NAMESPACES	all	監視対象の名前空間。カンマ区切りで指定するか、クラスター全体を対象にする場合は all を指定します
AI_MODEL	gemini-2.5-pro	Google GenAI SDK がサポートする任意のモデル名
LOG_LEVEL	INFO	Python のログレベル
REMEDIATION_MODE	api	api（Kubernetes クライアント。クラスター内で安全に使用できます）または subprocess（kubectl。ローカル開発専用）

AI_MODEL の変更にコードの変更は必要ありません。エージェントは設定されたモデル名を動的に使って、すべての LLM 呼び出しを振り分けます。

---

🔮 今後の予定

実装済みで動作している機能：

• 監視 → 診断 → 信頼度スコア付きの Slack 通知
• Slack のインタラクティブボタンを使った、人間の承認を介する修復
• OPA Gatekeeper のアドミッションサンドボックスを備えた一時的な Job 実行環境
• AI クライアントからオンデマンドで診断できる MCP サーバー — MCP Registry に io.github.JDoornink/k8gents として公開されています
• Gatekeeper を必須の依存関係とする Helm チャート

未解決の課題：

• 信頼度の較正 — 現在のスコアはモデルが自己申告する確信度を反映していますが、実際の精度との相関は安定していません。
• 決定論的な振り分け — CrashLoopBackOff や OOMKilled のように診断方法が確立している障害は、LLM を介さずに処理すべきです。「既知の答えがある」場合と「推論が必要」な場合を分類する、信頼性の高い実行時分類器の構築が、次の構造的な変更となります。
• 評価 — 新たな障害の検出を目的とするエージェントの回帰テストには、この問題領域に十分対応できるフレームワークがまだ存在しません。合成的な障害の注入（カオスエンジニアリング）が最も有望ですが、網羅できる範囲には本質的な限界があります。
• 修復後の検証 — 修正を実行した後、対象の名前空間を60秒間監視し、復旧を確認するか、クラッシュ状態が続いていることを知らせるフォローアップの Slack スレッドを投稿します。