Minio Aiops

Use this skill whenever the user needs to operate or diagnose MinIO object storage — explain why the cluster is filling up or refusing writes (capacity_rca), find publicly exposed buckets and hygiene gaps (bucket_exposure_audit), find storage that lifecycle/ILM should be reclaiming but isn't, including noncurrent versions and incomplete multipart uploads (lifecycle_gap_analysis), check heal backlog and erasure-set write-quorum risk (healing_health), read service health / cluster status / per-bucket config (policy, versioning, lifecycle, encryption, quota, tags) — plus governed writes (set or delete bucket policy, enable/suspend versioning, set or delete lifecycle rules, set bucket quota, purge incomplete uploads, delete an empty bucket). Always use this skill for "minio health", "why is my object storage full", "which bucket is biggest", "is any bucket public / anonymous access", "versioning / noncurrent versions piling up", "incomplete multipart uploads", "lifecycle / ILM rules", "bucket quota", "erasure set / drive failure tolerance", "healing backlog", or "delete a bucket safely" when the context is a MinIO deployment. Do NOT use when the target is not MinIO — for Ceph/RGW use ceph-aiops; for TrueNAS storage use truenas-aiops; for a hypervisor, backup product, container cluster, or network device route to the appropriate other AIops-tools skill (negative routing hint only). Common MinIO ops with a built-in governance harness (audit, policy, token budget, undo, risk-tiers).

Disclaimer: Community-maintained open-source project, not affiliated with, endorsed by, or sponsored by MinIO, Inc. or any storage vendor. Product and trademark names belong to their owners. Source at github.com/AIops-tools/MinIO-AIops under the MIT license.

Governed MinIO object-storage operations — 31 MCP tools, every one wrapped with the bundled @governed_tool harness: a local unified audit log under ~/.minio-aiops/, policy engine, token/runaway budget guard, undo-token recording, and graduated-autonomy risk tiers. The secret key is stored encrypted (~/.minio-aiops/secrets.enc, Fernet + scrypt) — never plaintext on disk. Four flagship analyses turn raw state into plain-language cause + suggested action: capacity_rca, bucket_exposure_audit, lifecycle_gap_analysis, healing_health.

Standalone: the governance harness is bundled in the package (minio_aiops.governance) — minio-aiops has no external skill-family dependency. Verification status and the live-run checklist are in docs/VERIFICATION.md.

Read-only mode: set MINIO_READ_ONLY=1 and the 9 write tools are not registered — they never appear in the tool list, and the harness refuses writes from any caller (MCP, CLI, in-process). Driving this with a smaller / local model? See references/agent-guardrails.md.

What This Skill Does

Group	Tools	Count	Read or Write
Health	health_live, health_ready, health_cluster, cluster_status, fleet_overview	5	5 read
Capacity	capacity_rca (flagship), usage_by_bucket	2	2 read
Healing	healing_health (flagship), drive_status, node_status	3	3 read
Exposure / ILM	bucket_exposure_audit (flagship), lifecycle_gap_analysis (flagship)	2	2 read
Buckets	bucket_ls, bucket_info, bucket_policy_get, bucket_lifecycle_get, bucket_versioning_get, bucket_quota_get, object_ls, incomplete_uploads_ls, server_info	9	9 read
Writes	set_bucket_policy, delete_bucket_policy, set_versioning, set_lifecycle, delete_lifecycle, set_bucket_quota, bucket_delete, remove_incomplete_uploads	8	8 write
Undo	undo_list, undo_apply	2	read + replay

Totals: 31 tools — 21 read, 8 write, 2 undo. The MCP server exposes all 31; the CLI is a convenience subset.

Quick Install

bash

uv tool install minio-aiops
minio-aiops init       # interactive wizard: endpoint + access key + encrypted secret key
minio-aiops doctor

When to Use This Skill

• "Storage is filling up / writes are failing" → capacity_rca (capacity vs used, offline drives/nodes, hotspots — cause + action per finding), then usage_by_bucket for the biggest consumers
• "Is anything exposed?" → bucket_exposure_audit (ranked: public read/write policies, missing encryption, versioning off, no lifecycle)
• "Where did my space go?" → lifecycle_gap_analysis (unbounded noncurrent versions, incomplete multipart uploads, reclaimable estimate) then remove_incomplete_uploads + set_lifecycle to fix it for good
• "How many more drives can fail?" → healing_health (per-erasure-set online drives vs write quorum, heal backlog/errors)
• One-shot triage (fleet_overview / minio-aiops overview): health + capacity headline + exposure headline
• Per-bucket questions: bucket_info (policy/versioning/lifecycle/encryption/quota/tags in one answer)
• Safely change policy/versioning/lifecycle/quota (reversible, undo recorded) or delete an empty bucket (governed, dry-run + double confirm)

Do NOT use when the target is not MinIO — for Ceph/RGW use ceph-aiops; for TrueNAS use truenas-aiops; for a hypervisor, backup product, container cluster, or network device route to the appropriate other AIops-tools skill.

Related Skills — Skill Routing

If the user wants…	Use
MinIO: capacity RCA, bucket exposure, ILM gaps, healing, bucket writes	minio-aiops (this skill)
Ceph/RGW storage	ceph-aiops
TrueNAS storage appliances	truenas-aiops
Any other target (hypervisor, backup, cluster, network)	the appropriate other AIops-tools skill

Common Workflows

Each recipe starts from an RCA read and ends in a governed, reversible write. Every write step accepts --dry-run; irreversible ones also double-confirm.

1. "Backups are failing — the cluster says it's out of space"

1. minio-aiops overview → one-shot triage: health + capacity headline + exposure headline.
2. minio-aiops capacity rca → ranked findings with cause + action (CLUSTER_NEARFULL, DRIVES_OFFLINE, DRIVE_HOTSPOT, …). Note which finding is actually driving the fill.
3. minio-aiops capacity usage → the biggest buckets, largest first, so you know where the bytes live.
4. minio-aiops bucket ilm-gap → how much of that is reclaimable: unbounded noncurrent versions and abandoned multipart uploads, with an estimate.
5. Reclaim the abandoned uploads: minio-aiops bucket purge-uploads <bucket> --older-than-days 7 --dry-run, then re-run without --dry-run (double confirm — this one is irreversible, only uploads older than the window are aborted).
6. Prevent recurrence: minio-aiops bucket lifecycle-set <bucket> --noncurrent-days 30 --abort-days 7 (reversible — the prior lifecycle config is captured).
7. minio-aiops capacity rca again to confirm the finding cleared.

Failure branch: if capacity rca reports DRIVES_OFFLINE rather than genuine data growth, stop — do not delete anything. The space is not gone, it is unavailable. Go to recipe 3 and restore drive/erasure-set health first; purging data under a degraded erasure set removes redundancy you may need.

2. "Someone says one of our buckets is readable from the internet"

1. minio-aiops bucket audit → ranked exposure findings, riskiest first (PUBLIC_WRITE_POLICY, PUBLIC_READ_POLICY, missing encryption, versioning off, no lifecycle).
2. minio-aiops bucket info <bucket> → the full per-bucket picture (policy, versioning, lifecycle, encryption, quota, tags) so you fix the right thing.
3. Decide the fix. To remove anonymous access entirely: minio-aiops bucket policy-set <bucket> --file restricted-policy.json --dry-run, then re-run for real. To drop the policy altogether, use the delete_bucket_policy MCP tool. Both are reversible — the prior policy JSON is captured.
4. minio-aiops undo list → confirm an undo token was recorded for the change you just made.
5. minio-aiops bucket audit → confirm the finding is gone.

Failure branch: if the write is refused with a policy/approval error, that is secure-by-default working. With no ~/.minio-aiops/rules.yaml, high-risk operations require a named approver — set MINIO_AUDIT_APPROVED_BY and MINIO_AUDIT_RATIONALE and retry. If the new policy breaks a legitimate consumer, minio-aiops undo apply <id> restores the exact prior policy document.

3. "A drive died — how many more failures can we take?"

1. minio-aiops health check and minio-aiops health status → is the cluster serving reads and writes at all right now?
2. minio-aiops heal status → per erasure set: online drives vs write quorum, failureToleranceRemaining, healing drives, heal backlog and errors.
3. minio-aiops heal drives → which specific drives are offline or healing.
4. minio-aiops heal nodes → whether the failures cluster on one node (a node problem, not a drive problem).
5. If WRITE_QUORUM_AT_EDGE appears, the next failure stops writes: replace drives before any maintenance, and re-run heal status until the backlog drains.

Failure branch: if the heal backlog is not shrinking between runs, do not start more maintenance. Check heal nodes for an offline node first — a down node makes its drives look like many simultaneous drive failures, and replacing hardware will not fix it.

4. "Decommission a retired bucket"

1. minio-aiops bucket ls → confirm the exact bucket name.
2. minio-aiops bucket info <bucket> → verify it is genuinely retired (check versioning, lifecycle and quota, not just the object count).
3. minio-aiops bucket uploads <bucket> → surface incomplete multipart uploads, which keep a bucket non-empty even when it looks empty.
4. minio-aiops bucket purge-uploads <bucket> --older-than-days 7 if any remain (dry-run first, double confirm).
5. minio-aiops bucket delete <bucket> --dry-run → shows the API call, changes nothing.
6. Re-run without --dry-run: double confirm, high risk, requires MINIO_AUDIT_APPROVED_BY/MINIO_AUDIT_RATIONALE. Execution re-checks emptiness (versions and delete markers included) and refuses otherwise — this tool never mass-deletes data.

Failure branch: if the delete is refused as non-empty, that is the guard doing its job — the bucket still holds objects, noncurrent versions, delete markers, or incomplete uploads. Go back to step 3, and never work around the guard by deleting data out-of-band; this tool deliberately has no mass-delete path.

Governance & Safety

• Every tool is audited to ~/.minio-aiops/audit.db (relocatable via MINIO_AIOPS_HOME).
• High-risk ops (bucket_delete) require a named approver: set MINIO_AUDIT_APPROVED_BY and MINIO_AUDIT_RATIONALE.
• Secure by default: with no ~/.minio-aiops/rules.yaml, high-risk operations are denied unless MINIO_AUDIT_APPROVED_BY names an approver. minio-aiops init seeds a starter rules.yaml; an operator-authored rules file is honoured as-is.
• Destructive writes support --dry-run and double confirmation at the CLI.
• Reversible writes record an inverse descriptor capturing the real prior state (policy JSON, lifecycle XML, versioning state, quota).

References

• references/capabilities.md — full tool → API-surface → returns reference
• references/cli-reference.md — CLI command reference
• references/setup-guide.md — onboarding, credentials, and connectivity