Ceph AIops

Ceph AIops

免責事項：コミュニティが保守するオープンソースプロジェクトです。**Ceph プロジェクトまたはいかなるストレージベンダーとも提携、推奨、後援関係にはありません。**製品名および商標名は各所有者に帰属します。MIT ライセンスです。

Ceph 向けのガバナンス機能を備えた AI 運用ツールです。標準の ceph-mgr Dashboard REST API （HTTPS :8443。ユーザー名とパスワードを POST /api/auth に送信し、短命の JWT と交換）に接続し、 組み込みのガバナンスハーネス（統合監査ログ、 トークン／暴走予算ガード、取り消しトークンの記録、説明的なリスクレベル）を備えています。 標準の ceph-mgr で動作し、cephadm、 ハイパーバイザーに同梱された Ceph、MicroCeph に対応しています。croit や Kubernetes への 依存はありません。自己完結型で、外部のスキルファミリーに依存しません。

できること

主要な分析機能と、それを支えるガード付きの読み取り／書き込み機能です。

• cluster_health — HEALTH_WARN/ERR の根本原因分析。 生のチェックコード （PG_DEGRADED、OSD_NEARFULL、SLOW_OPS、MON_DOWN、 LARGE_OMAP_OBJECTS、…）をそのまま返すのではなく、有効な各チェックを平易な言葉に変換します。 意味、考えられる原因、推奨される次のアクションを説明します。これは ceph -s を そのまま中継するだけの趣味の Ceph MCP と異なる点です。
• ガバナンス付きの破壊的操作。 運用担当者が実際に恐れる操作である osd_purge、pool_delete、set_pool_size、rbd_image_delete には、 ドライラン＋二重確認と高リスクレベルが設定されています。元に戻せるチューニング操作 （osd_reweight、throttle_recovery、cluster_flag_set、プールのクォータ／pg_num／ オートスケーリング）では、以前の状態を取得した取り消し記述子を記録します。

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

Ceph の操作（読み取りと書き込み）を正確かつ効率的に実行し、すべてを記録します。 書き込みを許可するかどうかは判断しません。それはエージェントの判断、または接続に使用する アカウントの権限です。読み取り専用ロールの ceph-mgr Dashboard アカウントを指定すれば、 書き込みは権限を実際に管理する場所である mgr で失敗します。

そのため、読み取り専用スイッチも、ポリシーファイルも、設定すべき承認ゲートもありません。 このツールが保証するのは、何も記録されずに実行されることがない点です。MCP 経由でも CLI 経由でも、すべての呼び出しが ~/.ceph-aiops/audit.db に監査レコードとして記録されます。 また、破壊的な書き込みでは引き続き実行前の状態を取得し、逆操作が存在する場合は記録します。

各ツールは risk_level を宣言します。テストによって [READ]／[WRITE] のドキュメントタグと一致するよう維持され、説明的なレベルとして監査レコードにも記録されます。 これにより、レビュー担当者はレコードが高リスクの削除操作であることを一目で確認できます。 これはラベルであり、ゲートではありません。

動作する機能

• CLI（ceph-aiops ...）：init、overview、health detail／health status、 osd tree/df/reweight/out/purge、secret set/list/rm/migrate/rotate-password、 doctor、mcp。osd out と osd purge には --dry-run と二重確認が必要です。
• MCP サーバー（ceph-aiops mcp または ceph-aiops-mcp）：全 37 個のツール （読み取り 17、書き込み 18、取り消し 2）。すべてに付属の @governed_tool ハーネスが適用されます。CLI は便利なサブセットであり、MCP のインターフェースが全ツールを提供します。
• 暗号化された認証情報：Dashboard のパスワードは暗号化ストア ~/.ceph-aiops/secrets.enc（Fernet + scrypt）に保存され、ディスク上に平文で保存されることはありません。 CEPH_AIOPS_MASTER_PASSWORD（MCP／CI）からマスターパスワードを取得するか、対話型プロンプト（CLI）で ロックを解除します。
• 可逆性：元に戻せる書き込みでは、以前の状態を取得し、逆操作を示す取り消し記述子を記録します （例：osd_reweight → 以前の重み、set_pool_quota → 以前のクォータ、throttle_recovery → 以前のバックフィル／リカバリー設定）。
• 安全性：破壊的な操作（osd_purge、osd_mark_out、pool_delete、 set_pool_size、rbd_image_delete、rbd_snapshot_delete）には、高リスクレベルが設定され、 dry_run と CLI での二重確認が必要です。

機能一覧（MCP ツール 37 種）

グループ	ツール	数	読み取り／書き込み
ヘルス	cluster_health（主要な RCA）、cluster_status	2	読み取り
OSD	osd_tree、osd_df、osd_perf	3	読み取り
	cluster_flag_set（低、取り消し可能）、osd_reweight（中、取り消し可能）、osd_mark_in（中、取り消し可能）	3	書き込み
	osd_mark_out（高、ドライラン）、osd_purge（高、ドライラン）	2	書き込み
PG	pg_summary、pg_dump_stuck、scrub_status	3	読み取り
	trigger_scrub（低）、trigger_deep_scrub（低）	2	書き込み
プール	pool_ls、pool_df	2	読み取り
	set_pool_quota（中、取り消し可能）、set_pool_pg_num（中、取り消し可能）、set_pool_autoscale（中、取り消し可能）、pool_create（中）	4	書き込み
	set_pool_size（高、ドライラン）、pool_delete（高、ドライラン）	2	書き込み
RBD	rbd_ls	1	読み取り
	rbd_image_create（中）、rbd_snapshot_create（低）	2	書き込み
	rbd_image_delete（高、ドライラン）、rbd_snapshot_delete（高、ドライラン）	2	書き込み
CephFS / RGW	cephfs_status、rgw_status	2	読み取り
クラスター運用	mon_status、mgr_status、slow_ops、capacity_forecast	4	読み取り
	throttle_recovery（中、取り消し可能）	1	書き込み
取り消し	undo_list、undo_apply	2	取り消し

合計：ツール 37 種 — 読み取り 17、書き込み 18、取り消し 2。

クイックスタート

Claude Code プラグインとして

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

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

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

OpenClaw プラグインとして

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

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

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

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

uv tool install ceph-aiops          # or: pipx install ceph-aiops
ceph-aiops init                     # wizard: add a mgr target + store the Dashboard password (encrypted)
ceph-aiops doctor                   # JWT login + mgr-dashboard reachability
ceph-aiops overview                 # HEALTH status + active checks + OSD up/in
ceph-aiops health detail            # decode the active HEALTH_WARN/ERR checks (RCA)
ceph-aiops osd df                   # per-OSD utilization, most-full first, near/backfill-full flags

MCP サーバーとして実行します（stdio）：

export CEPH_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
ceph-aiops-mcp

そのパスワードの保存場所：エクスポートした変数は、このシェルが起動するすべてのプロセスから読み取り可能で、シェル履歴にも記録されます。共有ホストや長時間稼働するホストでは、対話型プロンプトを使うか、必要なコマンドの実行中だけシークレットマネージャーから注入してください。

ガバナンス

MCP と CLI のどちらの操作も、同梱の @governed_tool ハーネスを通ります。記録は行いますが、認可は行いません（上記を参照）。

• 監査 — すべての呼び出し（パラメーター、結果、ステータス、所要時間、リスクレベル、およびオペレーターが指定した承認者／理由）は ~/.ceph-aiops/audit.db に記録されます（CEPH_AIOPS_HOME で保存先を変更できます）。CLI は MCP 経由と同じ行を記録するため、監査されない入り口はありません。
• 暴走防止 — 認可ゲートではなく、安全性を確保するための保護策です。同じ呼び出しが短時間に繰り返されると、サーキットブレーカーが作動し、停止したエージェントが呼び出しや時間を無制限に消費するのを防ぎます。CEPH_RUNAWAY_MAX=0 で無効化できます。必要に応じて CEPH_MAX_TOOL_CALLS／CEPH_MAX_TOOL_SECONDS で上限を設定できます。
• 取り消しの記録 — 元に戻せる書き込みでは、取得した変更前の状態から作成した逆操作の記述子を記録します。
• リスクレベル — risk_level から導出され、監査ログの行に付与される説明用ラベルです。何かを制限するものではありません。

対応範囲と制限事項

• デプロイ環境：dashboard モジュールが有効な標準の ceph-mgr — cephadm、ハイパーバイザーにバンドルされた Ceph、または MicroCeph。croit は対象外で、Kubernetes への依存もありません。
• Ceph の Dashboard API には ETag とページネーションがありません。そのため、このツールではどちらも提供していません。機能が欠けているのではなく、上流の API がそもそも提供していません。
• 検証状況：動作は、テストスイートでモックした Dashboard のレスポンスを使って確認しています。複数ノードのリバランスと書き込み操作は、実稼働クラスターではまだ実行していません。最も手軽な実環境での確認方法は、単一ノードの MicroCeph（snap install microceph → ブートストラップ → ループファイル OSD）で ceph-aiops doctor を実行することです。3 ノードの Vagrant クラスターでは、実際のリバランス動作を確認できます。実環境での検証チェックリスト全体は、docs/VERIFICATION.md を参照してください。

必要な機能がありませんか？

RGW マルチサイト、デーモンごとの設定の分散、NFS-Ganesha のエクスポート、オーケストレーター（cephadm）によるホスト管理には、まだ対応していません。issue を作成するか、PR を送ってください。フィードバックや貢献を歓迎します。