K8s-AIops

<!-- mcp-name: io.github.AIops-tools/k8s-aiops -->
# 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](https://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](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](skills/k8s-aiops/references/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](https://docs.astral.sh/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 a CLI or standalone MCP server

```bash
uv tool install k8s-aiops

# Friendly onboarding wizard — registers your kube contexts as named targets:
k8s-aiops init

# Or skip it — uses your current kube-context out of the box:
k8s-aiops doctor
k8s-aiops pod list
k8s-aiops deployment list -n default

# Read-only RCA — worst-first root-cause findings, no changes made:
k8s-aiops diagnose pod-health -n prod
k8s-aiops diagnose workload-readiness -n prod
```

To define named targets (multiple clusters/contexts), create
`~/.k8s-aiops/config.yaml`:

```yaml
targets:
  - name: prod          # used as -t prod
    context: prod-eks   # a context in your kubeconfig (omit for current-context)
    namespace: default  # optional default namespace
    # kubeconfig: /path/to/alt/kubeconfig   # optional explicit path
  - name: lab
    context: k3s-lab
```

No secrets live in this file — credentials come from the kubeconfig.

## MCP

```jsonc
{
  "command": "k8s-aiops",
  "args": ["mcp"],
  "env": { "K8S_AIOPS_CONFIG": "~/.k8s-aiops/config.yaml" }
}
```

> **Note — MCP servers get a clean environment**: most MCP clients spawn the
> server without your shell's exports, so variables like `K8S_AIOPS_HOME`,
> `K8S_AUDIT_APPROVED_BY`, `K8S_AUDIT_RATIONALE` (and `KUBECONFIG`, if your
> kubeconfig is not at `~/.kube/config`) must be set in the MCP server
> config's `env` block above — values exported only in your terminal may
> never reach the server.

## Audit & Safety

- Every tool call is logged to `~/.k8s-aiops/audit.db` (local SQLite; relocate with
  `K8S_AIOPS_HOME`).
- Reversible writes record an inverse undo descriptor (`scale_deployment` →
  scale-back to previous; `cordon_node` ↔ `uncordon_node`).
- Every MCP write tool takes `dry_run=True` and returns a `{"dryRun": true, ...}`
  preview without touching the cluster (no undo recorded for a preview).
- `delete_deployment` is `risk_level=high`; destructive CLI commands require double
  confirmation, medium-risk ones (`deployment scale`/`restart`) a single
  confirmation, and all write commands support `--dry-run`.
- All API text passes through `sanitize()` (output hygiene: control/format-char
  stripping + truncation).

See `skills/k8s-aiops/SKILL.md` and `SECURITY.md` for details.

## Secrets

k8s-aiops deliberately has **no encrypted secret store** (no `secrets.enc`, no
`secret` CLI): authentication is delegated entirely to your kubeconfig — client
certificates, bearer tokens, or exec plugins (EKS/GKE/AKS) — and the tool never
handles or stores cluster credentials itself. This is a documented exception to
the AIops-tools line-wide encrypted-secret-store pattern.

## Companion Skills

| If you want… | Use |
|--------------|-----|
| Kubernetes pods / deployments / nodes | **k8s-aiops** (this) |
| Hypervisor VM lifecycle | a hypervisor ops skill |
| Backup & restore | a backup ops skill |

## Contributing & feature requests

Coverage is intentionally focused. **Missing a device, action, or feature you need?** Open an issue or pull request at [github.com/AIops-tools/K8s-AIops](https://github.com/AIops-tools/K8s-AIops/issues) — feature requests, contributions, and comments are all welcome.

## License

MIT — [github.com/AIops-tools/K8s-AIops](https://github.com/AIops-tools/K8s-AIops)