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:

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

The MCP server is fetched with uv and pinned to the package version this plugin declares, so an audit row can be traced back to the code that wrote it. Credentials are still configured with k8s-aiops init — see below.

As an OpenClaw plugin

The same bundle is published on ClawHub, where one install delivers the skill and its MCP server together:

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