k8s AIops

k8s-aiops

免責事項：本プロジェクトはコミュニティによって保守されているオープンソースプロジェクトであり、Cloud Native Computing Foundation、Kubernetes プロジェクト、または k3s/Rancher とは提携、承認、後援の関係にありません。「Kubernetes」と「k3s」は、それぞれの所有者の商標です。ソースコードは、MIT ライセンスの下、github.com/AIops-tools/K8s-AIops で公開され、監査可能です。

AI エージェント向けのガバナンスされた Kubernetes 運用 — 55 個の MCP ツールを備え、すべてに同梱の @governed_tool ハーネスが適用されています。これには、~/.k8s-aiops/ 配下のローカル統合監査ログ、トークン／暴走予算ガード、取り消しトークンの記録、各監査行への説明的なリスク階層ラベルが含まれます。対象は、ポッド、デプロイメント、ステートフルセット、デーモンセット、レプリカセット、ジョブ／cronjob、サービス、イングレス、エンドポイント、コンフィグマップ、シークレット（名前／キーのみ）、PVC／PV／ストレージクラス、ノード、ネームスペース、イベント、ロールアウト（ステータス／履歴／取り消し／一時停止／再開／イメージ設定）、ポッド／ノードの詳細情報、ポッド／ノードの使用状況、クラスターの健全性サマリー、そして読み取り専用の診断／根本原因分析（RCA）（ポッドの健全性とワークロードの準備状況）です。これらは根本原因を深刻度の高い順に示します。

単独で利用可能：ガバナンスハーネスはパッケージ（k8s_aiops.governance）に同梱されているため、k8s-aiops に外部のスキルファミリー依存関係はありません。対象範囲は一般的なクラスター運用に重点を置いており、まだ網羅的ではありません。

検証状況：稼働中の kind クラスター（v1.36）に対してエンドツーエンドで検証済みです。このリリースで追加された診断／RCA ツールは、モックテストのみ実施しています。docs/VERIFICATION.md を参照してください。

動作する環境

kubeconfig から接続できる任意のクラスターで利用できます。標準の Kubernetes、k3s、EKS、GKE、AKS、kind、minikube に対応しています。認証（クライアント証明書、トークン、EKS/GKE/AKS の exec プラグイン）は、すべて kubeconfig に委ねられます。

このツールが判断すること／しないこと

このツールは Kubernetes の運用（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを許可するかどうかは判断しません。それはエージェントの判断、または接続先の kubeconfig コンテキスト／ServiceAccount の権限によります。読み取り専用の RBAC ロールに紐付いたコンテキストを指定すれば、書き込みは apiserver で失敗します。実際に権限を管理しているのは apiserver です。

そのため、読み取り専用スイッチも、ポリシーファイルも、設定が必要な承認ゲートもありません。このツールが保証するのは、何も黙って実行されないことです。MCP 経由でも CLI 経由でも、すべての呼び出しは ~/.k8s-aiops/audit.db に監査行として記録され、破壊的な書き込みでは実行前の状態が取得され、可能な場合は逆操作も記録されます。暴走予算ガードは安全対策であり、認可の仕組みではありません。

各ツールには risk_level が宣言されており、テストによって [READ]／[WRITE] のドキュメントタグとの整合性が保たれています。また、説明用の階層として監査行にも記録されるため、レビュー担当者は高リスクの削除だったことをひと目で確認できます。これはラベルであり、実行を制限するゲートではありません。

より小規模なモデルやローカルモデルを実行していますか？agent-guardrails.md をご覧ください。このツールが代わりに適用するガードレール（そのため、同じ内容をプロンプトのトークン予算を使って繰り返し記述する必要はありません）と、残りの内容に使えるすぐに利用可能なシステムプロンプトが記載されています。

クイックスタート

Claude Code プラグインとして

1 回のインストールで、エージェントにスキルと MCP サーバーの両方を導入できます。

/plugin marketplace add AIops-tools/marketplace
/plugin install k8s-aiops@aiops-tools

MCP サーバーは uv で取得され、このプラグインが宣言するパッケージバージョンに固定されます。そのため、監査行を、それを書き込んだコードまでたどることができます。認証情報は引き続き k8s-aiops init で設定します。以下を参照してください。

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されており、1 回のインストールでスキルと MCP サーバーをまとめて導入できます。

openclaw plugins install clawhub:@zw008/k8s-aiops
openclaw skills info k8s-aiops          # expect: Visible to model: yes

その後、プラグインを読み込むために OpenClaw ゲートウェイを再起動してください。MCP サーバーは uv を使って取得され、このリリースに固定されているため、uvx が PATH に含まれている必要があります。含まれていない場合でもスキルはインストールされますが、Visible to model: no と表示されます。認証情報は以下のとおりに設定します。

CLI またはスタンドアロン MCP サーバーとして

uv tool install k8s-aiops

# Friendly onboarding wizard — registers your kube contexts as named targets:
k8s-aiops init

# Or skip it — uses your current kube-context out of the box:
k8s-aiops doctor
k8s-aiops pod list
k8s-aiops deployment list -n default

# Read-only RCA — worst-first root-cause findings, no changes made:
k8s-aiops diagnose pod-health -n prod
k8s-aiops diagnose workload-readiness -n prod

名前付きターゲット（複数のクラスター／コンテキスト）を定義するには、~/.k8s-aiops/config.yaml を作成します。

targets:
  - name: prod          # used as -t prod
    context: prod-eks   # a context in your kubeconfig (omit for current-context)
    namespace: default  # optional default namespace
    # kubeconfig: /path/to/alt/kubeconfig   # optional explicit path
  - name: lab
    context: k3s-lab

このファイルにシークレットは保存されません。認証情報は kubeconfig から取得されます。

MCP

{
  "command": "k8s-aiops",
  "args": ["mcp"],
  "env": { "K8S_AIOPS_CONFIG": "~/.k8s-aiops/config.yaml" }
}

注 — MCP サーバーにはクリーンな環境が渡されます：ほとんどの MCP クライアントは、シェルでエクスポートした環境変数を引き継がずにサーバーを起動します。そのため、K8S_AIOPS_HOME、K8S_AUDIT_APPROVED_BY、K8S_AUDIT_RATIONALE（および kubeconfig が ~/.kube/config にない場合は KUBECONFIG）などの変数は、上記の MCP サーバー設定の env ブロックで設定する必要があります。ターミナルでのみエクスポートした値は、サーバーに渡されない場合があります。

監査と安全性

• すべてのツール呼び出しは ~/.k8s-aiops/audit.db に記録されます（ローカルの SQLite。保存先は K8S_AIOPS_HOME で変更できます）。
• 元に戻せる書き込みでは、逆操作の記述子が記録されます（scale_deployment → 前のスケール値に戻す、cordon_node ↔ uncordon_node）。
• すべての MCP 書き込みツールは dry_run=True を受け取り、クラスターに変更を加えることなく {"dryRun": true, ...} のプレビューを返します（プレビューでは取り消し情報は記録されません）。
• delete_deployment は risk_level=high です。破壊的な CLI コマンドには二重の確認、中リスクのコマンド（deployment scale／restart）には 1 回の確認が必要です。すべての書き込みコマンドは --dry-run に対応しています。
• すべての API テキストは sanitize() を通ります（出力の衛生処理：制御文字／書式文字の除去と切り詰め）。

詳しくは skills/k8s-aiops/SKILL.md と SECURITY.md を参照してください。

シークレット

k8s-aiops には、意図的に暗号化されたシークレットストアがありません（secrets.enc も secret CLI もありません）。認証はすべて kubeconfig に委ねられています。kubeconfig では、クライアント証明書、ベアラートークン、exec プラグイン（EKS／GKE／AKS）を使用できます。ツールがクラスターの認証情報を扱ったり、保存したりすることはありません。これは、AIops-tools 全体で採用されている暗号化シークレットストアのパターンに対する、文書化された例外です。

関連スキル

使用目的…	使用するもの
Kubernetes のポッド／デプロイメント／ノード	k8s-aiops（本ツール）
ハイパーバイザーの VM ライフサイクル	ハイパーバイザー運用スキル
バックアップと復元	バックアップ運用スキル

コントリビューションと機能リクエスト

対応範囲は意図的に絞っています。必要なデバイス、アクション、機能が不足していますか？ github.com/AIops-tools/K8s-AIops でイシューまたはプルリクエストを作成してください。機能リクエスト、コントリビューション、コメントを歓迎します。

ライセンス

MIT — github.com/AIops-tools/K8s-AIops