AIops-tools/K8s-AIops

> **Disclaimer**: This is a community-maintained open-source project and is **not
> affiliated with, endorsed by, or sponsored by the Cloud Native Computing
> Foundation, the Kubernetes project, or k3s/Rancher.** "Kubernetes" and "k3s" are
> trademarks of their respective owners. Source code is publicly auditable at
> github.com/AIops-tools/K8s-AIops under
> the MIT license.
Governed Kubernetes operations for AI agents — **55 MCP tools**, every one wrapped
with the bundled @governed_tool harness: a local unified audit log under
~/.k8s-aiops/, a token/runaway budget guard, undo-token recording, and a
descriptive risk-tier label on every audit row. Coverage spans pods, deployments, statefulsets,
daemonsets, replicasets, jobs/cronjobs, services, ingresses, endpoints,
configmaps, secrets (names/keys only), PVCs/PVs/storageclasses, nodes, namespaces,
events, rollouts (status/history/undo/pause/resume/set-image), pod/node describe,
pod/node top, a cluster health summary, and read-only **diagnostics / RCA**
(pod-health and workload-readiness) that flag the root cause worst-first.
> **Standalone**: the governance harness is bundled in the package
> (k8s_aiops.governance) — k8s-aiops has no external skill-family dependency.
> Coverage focuses on common cluster operations and is not yet exhaustive.
> **Verification status**: exercised end-to-end against a live kind cluster (v1.36); the
> diagnostics/RCA tools added in this release are mock-tested only. See
> docs/VERIFICATION.md.
What works
Any cluster a kubeconfig can reach: standard Kubernetes, **k3s**, **EKS**, **GKE**,
**AKS**, kind, minikube. Authentication (client certs, tokens, EKS/GKE/AKS exec
plugins) is delegated entirely to the kubeconfig.
What this tool does, and does not, decide
It delivers Kubernetes operations — reads and writes — accurately and
efficiently, and records every one of them. It does **not** decide whether a
write is allowed to happen. That is the agent's judgement, or the permission of
the kubeconfig context / ServiceAccount you connect it with: point it at a
context bound to a read-only RBAC role and the writes fail at the apiserver —
the place that actually owns the permission.
So there is no read-only switch, no policy file, no approval gate to configure.
The one thing the tool guarantees is that nothing is silent: **every call, over
MCP and over the CLI alike, lands an audit row** in ~/.k8s-aiops/audit.db, and
destructive writes still capture their before-state and record an inverse where
one exists. The runaway budget guard is a safety backstop, not authorization.
> Each tool declares a risk_level, kept in agreement with its [READ]/[WRITE]
> documentation tag by a test, and carried into the audit row as a descriptive
> tier — so a reviewer can see at a glance that a row was a high-risk delete. It
> is a label, not a gate.
Running a smaller / local model? See
agent-guardrails.md — it lists
the guardrails this tool now enforces for you (so you don't spend prompt budget
restating them) and gives a ready-made system prompt for what's left.
Quick Start
As a Claude Code plugin
One install gives an agent both the skill and the MCP server:
The MCP server is fetched with uv and pinned to the