MinIO AIops

MinIO AIops

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

MinIO オブジェクトストレージ向けの、ガバナンス機能を備えた AI 運用です。MinIO が実際に利用されているホームラボや、小規模・中規模のセルフホスト可能なデプロイメントを対象としています。S3 API（公式の minio SDK、SigV4）、管理 API（バケットクォータ、サーバー情報）、認証不要のヘルスエンドポイント（/minio/health/live|ready|cluster）、クラスターメトリクスエンドポイント（/minio/v2/metrics/cluster、ベアラートークンまたはパブリック認証）に接続し、さらに組み込みのガバナンスハーネスを備えています。統合監査ログ、トークン／暴走予算ガード、取り消しトークンの記録、各監査行の説明的なリスクティアを提供します。自己完結型で、外部のスキルファミリーに依存しません。

できること

主な分析機能が4つあり、それらを支えるガード付きの読み取り・書き込み機能も備えています。

• capacity_rca — 容量と使用量、オフラインのドライブ／ノード、ドライブごとのホットスポットと偏りを分析し、各検出事項を原因＋推奨アクションとして提示します（nearfull／full のしきい値はマジックナンバーではなく、名前付き定数です）。
• bucket_exposure_audit — すべてのバケットを評価し、順位付けします。匿名／パブリックポリシー文（読み取り、およびはるかに危険な書き込み）、デフォルト暗号化の未設定、バージョニングの無効化、ライフサイクルの未設定を検出します。
• lifecycle_gap_analysis — ストレージ ILM で回収されるはずの領域が回収されていない状態を検出します。noncurrent の有効期限設定がないバージョニング有効バケット（古いデータが際限なく蓄積）、中止ルールがない不完全なマルチパートアップロード（見えない領域を消費）、ライフサイクルが設定されていない大容量バケットなどを検出し、回収可能な容量の推定値を明確に表示します。
• healing_health — ヒール処理の滞留状況と、イレイジャーセットごとの書き込みクォーラムのリスクを分析します。各セットがあと何台のドライブ障害に耐えられるか、どのセットがヒール中か、どこでヒールエラーが蓄積しているかを示します。
• ガバナンス付きの書き込み。バケットポリシー／バージョニング／ライフサイクル／クォータの変更では、実際の変更前の状態を取得して、取り消し記述子を記録します。bucket_delete はバケットが確実に空であると検証されない限り拒否されます（バージョンと削除マーカーも含めて確認）。remove_incomplete_uploads は安全期間より古いアップロードのみを対象とします。

対応機能

• CLI（minio-aiops ...）：init、overview、doctor、health check/status、capacity rca/usage、heal status/drives/nodes、bucket ls/info/objects/audit/ilm-gap/uploads と、ガード付き書き込み（bucket versioning-set/policy-set/lifecycle-set/quota-set/purge-uploads/delete）、 secret set/list/rm/migrate/rotate-password、mcp。破壊的なコマンドでは --dry-run と二重確認が必須です。
• MCP サーバー（minio-aiops mcp または minio-aiops-mcp）：すべての48 ツール（読み取り29、書き込み19）を提供し、各ツールは同梱の @governed_tool ハーネスでラップされています。CLI は便利な機能を一部に絞ったもので、 MCP のインターフェースがツール全体を提供します。CLI の書き込みは同じガバナンス付き関数に 委譲されるため、同じ方法で監査されます。
• 暗号化された認証情報：シークレットキーは暗号化ストア ~/.minio-aiops/secrets.enc（Fernet + scrypt）に保存されます。ディスク上に 平文で保存されることはありません。MINIO_AIOPS_MASTER_PASSWORD のマスターパスワードで ロックを解除するか（MCP／CI）、CLI では対話型プロンプトで入力します。
• 2種類のメトリクス認証方式：MINIO_PROMETHEUS_AUTH_TYPE=public で実行されている サーバーは直接スクレイピングします。デフォルトの（jwt）モードでは、ベアラートークンは 保存済みの認証情報から導出されるため、追加のシークレットを管理する必要はありません。
• 可逆性：元に戻せる書き込みでは変更前の状態を取得し、逆操作用の取り消し記述子 （変更前のポリシー JSON、ライフサイクル XML、バージョニング状態、クォータ）を記録します。

機能一覧（48 個の MCP ツール）

グループ	ツール	数	読み取り／書き込み
ヘルス	health_live、health_ready、health_cluster、cluster_status、fleet_overview	5	読み取り
容量	capacity_rca（主要機能）、usage_by_bucket	2	読み取り
修復	healing_health（主要機能）、drive_status、node_status	3	読み取り
公開状態／ILM	bucket_exposure_audit（主要機能）、lifecycle_gap_analysis（主要機能）	2	読み取り
バケット	bucket_ls、bucket_info、bucket_policy_get、bucket_lifecycle_get、bucket_versioning_get、bucket_quota_get、object_ls、incomplete_uploads_ls、server_info	9	読み取り
書き込み	set_bucket_policy（中リスク、元に戻せます）、delete_bucket_policy（中リスク、元に戻せます）、set_versioning（中リスク、元に戻せます）、set_lifecycle（中リスク、元に戻せます）、delete_lifecycle（中リスク、元に戻せます）、set_bucket_quota（中リスク、元に戻せます）	6	書き込み
	bucket_delete（高リスク、ドライラン、空の場合のみ、取り消し不可）、remove_incomplete_uploads（中リスク、ドライラン、priorState のみ）	2	書き込み
オブジェクトロック（WORM）	bucket_lock_config、object_lock_status、diagnose_retention_gaps（主要機能）	3	読み取り
	bucket_create（中リスク、元に戻せます — オブジェクトロックを有効にする唯一の方法）、set_default_retention（高リスク、元に戻せます）、clear_default_retention（中リスク、元に戻せます）、set_legal_hold（中リスク、元に戻せます）	4	書き込み
	set_object_retention（重大、ドライラン、延長のみ、元に戻す方法はありません）	1	書き込み
IAM	iam_users、iam_groups、iam_policies、diagnose_iam_exposure（主要機能）	4	読み取り
	create_user（中リスク、元に戻せます、シークレットは秘匿され、返されません）、set_user_status（中リスク、元に戻せます）、attach_user_policy（中リスク、元に戻せます）、detach_user_policy（中リスク、元に戻せます）— このツール自身の認証情報にはすべて拒否されます	4	書き込み
	remove_user（高リスク、ドライラン、元に戻せません：MinIO は復元可能なシークレットを保持しません）	1	書き込み
取り消し	undo_list、undo_apply	2	読み取り＋再実行

合計：48 個のツール — 読み取り 29 個（undo_list を含む）、書き込み 19 個（undo_apply を含む）。

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

このツールは、MinIO オブジェクトストレージに対する読み取りと書き込みの操作を正確かつ効率的に実行し、そのすべてを記録します。書き込みを許可するかどうかは判断しません。それを判断するのはエージェント、または接続に使用するアクセスキーの権限です。キーに読み取り専用の IAM ポリシーを付与すれば、実際に権限を管理するサーバー側で書き込みが失敗します。

そのため、読み取り専用スイッチも、ポリシーファイルも、設定が必要な承認ゲートもありません。このツールが保証するのは、操作がひそかに行われないことです。MCP 経由でも CLI 経由でも、すべての呼び出しが ~/.minio-aiops/audit.db に監査レコードを残し、元に戻せる書き込みでは実際の実行前状態も取得したうえで、逆操作の取り消し記述子を記録します。

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

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

クイックスタート

Claude Code プラグインとして

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

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

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

OpenClaw プラグインとして

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

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

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

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

uv tool install minio-aiops         # or: pipx install minio-aiops
minio-aiops init                    # wizard: endpoint + access key; secret key stored encrypted
minio-aiops doctor                  # live/ready + S3 auth + metrics reachability
minio-aiops overview                # health + capacity headline + exposure headline
minio-aiops capacity rca            # why is storage filling up, and what to do
minio-aiops bucket audit            # ranked bucket-exposure findings

MCP サーバーとして実行する場合（stdio）：

export MINIO_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
minio-aiops-mcp

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

MCP クライアントの設定

{
  "mcpServers": {
    "minio-aiops": {
      "command": "uvx",
      "args": ["--from", "minio-aiops", "minio-aiops-mcp"],
      "env": { "MINIO_AIOPS_MASTER_PASSWORD": "your-master-password" }
    }
  }
}

環境ブロックに関する注意：MCP クライアントは TTY なし、シェルプロファイルなし でサーバーを起動するため、マスターパスワードの入力を促すことはできず、~/.zshrc 内の export も認識されません。上記のように、クライアントの env ブロック（またはクライアントプロセスの環境変数）で渡す必要があります。それ以外の設定（ターゲット、TLS、リージョン、メトリクスモード）はすべて、minio-aiops init が書き込む ~/.minio-aiops/config.yaml から取得されます。

設定

~/.minio-aiops/config.yaml（シークレット以外の接続情報のみ）：

targets:
  - name: lab1
    host: 192.0.2.10
    port: 9000
    access_key: minio-ops        # identifies the account; NOT the secret
    secure: true                 # https (false for plain-http labs)
    verify_ssl: true             # false for self-signed lab certs
    region: ""                   # optional
    metrics_public: false        # true when MINIO_PROMETHEUS_AUTH_TYPE=public

シークレットキーは minio-aiops secret set lab1 で保存されます（暗号化されます。従来の MINIO_LAB1_SECRET_KEY 環境変数は、移行警告とともにフォールバックとして使用されます）。

ガバナンス

すべてのMCPツールは、同梱の @governed_tool ハーネスを通過します。

• 監査 — すべての呼び出し（パラメーター、結果、ステータス、所要時間、リスクティア、および MINIO_AUDIT_APPROVED_BY / MINIO_AUDIT_RATIONALE の注釈があればその内容）は、~/.minio-aiops/audit.db に記録されます（MINIO_AIOPS_HOME で保存先を変更できます）。
• 予算／暴走防止ガード — トークン数と呼び出し数の予算を超えると、サーキットブレーカーが作動します。これは安全策であり、認可の仕組みではありません。
• リスクティアのラベル付け — 各ツールで宣言された risk_level は、監査レコードに説明用のティアとして記録されます（bucket_delete は high）。これはレビュー担当者向けのラベルであり、制限ではありません。読み取り専用スイッチ、ポリシーファイル、承認ゲートはありません。また、MINIO_AUDIT_APPROVED_BY / MINIO_AUDIT_RATIONALE は任意の注釈で、設定されていれば記録されますが、必須ではありません。
• 取り消し記録 — 元に戻せる書き込みでは、取得した変更前の状態に基づいて逆操作の記述子が記録されます。

対応範囲と制限事項

• デプロイ：S3 ポート経由で到達可能な、十分に新しい任意の MinIO サーバー（シングルノードまたは分散／イレイジャーコーディング構成）。管理機能（クォータ、server_info）には管理者権限を持つキーが必要です。一般的な S3 サービスは対象外です。ここで使用するヘルス／メトリクス／管理用のインターフェースは MinIO 固有です。
• メトリクス：容量／修復の RCA は v2 クラスターメトリクス エンドポイントを読み取ります。public モードと、ベアラートークン（デフォルト）認証モードの両方に対応しています。
• 不完全アップロードの一覧表示では、SDK のコアである ListMultipartUploads 呼び出しを使用します（公開エイリアスは SDK から削除されています）。テストで実行され、connection.py に記載されています。
• 検証状況。 実際のシングルノード MinIO サーバーでライブ検証済み（2026-07-19）：接続、読み取り、公開状態の監査（匿名で書き込み可能なバケットを正しく high と評価し、PUBLIC_WRITE_POLICY と特定）、およびガバナンスループ（実際の set_versioning → 元に戻す操作で Suspended に復元し、正しい S3 逆操作を実行）。分散／マルチノード MinIO は未検証のままです。劣化したドライブやイレイジャーセットに対する修復は実サーバーで一度も実行されておらず、ライフサイクル／クォータの書き込みや TLS エンドポイントも未検証です。docs/VERIFICATION.mdを参照してください。minio-aiops doctor が最も手早いライブチェックです。

欲しい機能がありませんか？

サイトのレプリケーション状況、IAM ポリシーの作成（ポリシードキュメントの作成と編集 — アタッチには対応しています）、グループメンバーシップの書き込み、リモートストレージへの階層化には、まだ対応していません。Issue を作成するか、PR を送ってください。フィードバックや貢献を歓迎します。