k8s-aiops 0.1.0__tar.gz

k8s_aiops-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual envs / build
+.venv/
+dist/
+build/
+
+# uv
+uv.lock
+
+# Local config / secrets (never commit)
+*.env
+.env
+config.yaml
+
+# OS
+.DS_Store

k8s_aiops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei <zhouwei008@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

k8s_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: k8s-aiops
+Version: 0.1.0
+Summary: Governed Kubernetes operations for AI agents with a built-in governance harness (audit, budget, undo, risk tiers)
+Author-email: wei <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: kubernetes<32,>=29
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.AIops-tools/k8s-aiops -->
+# k8s-aiops (preview)
+
+> **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 — **15 MCP tools**, every one wrapped
+with the bundled `@governed_tool` harness: a local unified audit log under
+`~/.k8s-aiops/`, policy engine, token/runaway budget guard, undo-token recording, and
+graduated-autonomy risk tiers.
+
+> **Standalone**: the governance harness is bundled in the package
+> (`k8s_aiops.governance`) — k8s-aiops has no external skill-family dependency.
+> Preview: common cluster operations, not yet exhaustive.
+
+## 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.
+
+## Quick Start
+
+```bash
+uv tool install k8s-aiops
+
+# Uses your current kube-context out of the box:
+k8s-aiops doctor
+k8s-aiops pod list
+k8s-aiops deployment list -n default
+```
+
+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" }
+}
+```
+
+## 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`).
+- `delete_deployment` is `risk_level=high`; CLI destructive commands require double
+  confirmation and support `--dry-run`.
+- All API text passes through `sanitize()` (prompt-injection defense).
+
+See `skills/k8s-aiops/SKILL.md` and `SECURITY.md` for details.
+
+## 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 |
+
+## License
+
+MIT — [github.com/AIops-tools/K8s-AIops](https://github.com/AIops-tools/K8s-AIops)

k8s_aiops-0.1.0/README.md

@@ -0,0 +1,84 @@
+<!-- mcp-name: io.github.AIops-tools/k8s-aiops -->
+# k8s-aiops (preview)
+
+> **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 — **15 MCP tools**, every one wrapped
+with the bundled `@governed_tool` harness: a local unified audit log under
+`~/.k8s-aiops/`, policy engine, token/runaway budget guard, undo-token recording, and
+graduated-autonomy risk tiers.
+
+> **Standalone**: the governance harness is bundled in the package
+> (`k8s_aiops.governance`) — k8s-aiops has no external skill-family dependency.
+> Preview: common cluster operations, not yet exhaustive.
+
+## 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.
+
+## Quick Start
+
+```bash
+uv tool install k8s-aiops
+
+# Uses your current kube-context out of the box:
+k8s-aiops doctor
+k8s-aiops pod list
+k8s-aiops deployment list -n default
+```
+
+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" }
+}
+```
+
+## 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`).
+- `delete_deployment` is `risk_level=high`; CLI destructive commands require double
+  confirmation and support `--dry-run`.
+- All API text passes through `sanitize()` (prompt-injection defense).
+
+See `skills/k8s-aiops/SKILL.md` and `SECURITY.md` for details.
+
+## 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 |
+
+## License
+
+MIT — [github.com/AIops-tools/K8s-AIops](https://github.com/AIops-tools/K8s-AIops)

k8s_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,78 @@
+# Security Policy
+
+## 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.
+
+## Reporting Vulnerabilities
+
+Report security issues privately to **zhouwei008@gmail.com** or via a GitHub
+private security advisory on the repository. Please do not open public issues for
+undisclosed vulnerabilities.
+
+## Security Design
+
+### Credential Management
+
+k8s-aiops does **not** store or handle cluster credentials directly. All
+authentication is delegated to the kubeconfig (`KUBECONFIG` env or `~/.kube/config`),
+which may hold client certificates, bearer tokens, or exec plugins (for EKS/GKE/AKS).
+The skill loads a kube context via the official `kubernetes` client and never reads,
+logs, or echoes the underlying credentials. The state directory `~/.k8s-aiops` should
+be owner-only (`chmod 700`); the skill warns if it is more permissive.
+
+### Destructive Operation Safety
+
+Write operations (scale, rollout restart, delete pod, delete deployment, cordon)
+all pass through the bundled `@governed_tool` decorator: policy pre-check, token /
+runaway budget guard, graduated-autonomy risk-tier gate, and audit logging. The CLI
+layer additionally requires double confirmation and supports `--dry-run` for the
+most destructive commands (deployment delete, pod delete, node cordon). Reversible
+writes record an inverse undo descriptor — `scale_deployment` records a scale-back to
+the previous replica count; `cordon_node` ↔ `uncordon_node` are mutual inverses.
+`delete_pod`, `delete_deployment`, and `rollout_restart_deployment` declare no undo;
+`delete_deployment` is tagged `risk_level=high`.
+
+### Least Privilege
+
+Use a kube context bound to a ServiceAccount or user with only the RBAC verbs you
+need. Read-only use requires only `get`/`list`/`watch`; the write tools additionally
+need `patch`/`delete` on the relevant resources.
+
+### Webhooks / Outbound Network
+
+None. The skill makes no outbound network calls beyond the configured Kubernetes API
+server. There are no background services or post-install scripts.
+
+### TLS Verification
+
+TLS verification follows the kubeconfig (`certificate-authority` / `insecure-skip-tls-verify`).
+The skill does not weaken it; disable verification only in the kubeconfig itself and
+only for self-signed lab clusters.
+
+### Prompt Injection Protection
+
+All text returned from the Kubernetes API (names, log lines, event messages) is run
+through `sanitize()` — truncation plus C0/C1 control-character stripping — before
+reaching the agent.
+
+### Transitive Dependencies
+
+`kubernetes` (official Python client), `typer`/`rich` (CLI), `pyyaml` (config), and
+the MCP SDK. No external skill-family dependency — the governance harness is vendored
+under `k8s_aiops.governance`.
+
+## Static Analysis
+
+```bash
+uvx bandit -r k8s_aiops/ mcp_server/
+```
+
+## Supported Versions
+
+The latest released version (currently 0.1.0, preview) receives security fixes.

k8s_aiops-0.1.0/k8s_aiops/__init__.py

@@ -0,0 +1,10 @@
+"""k8s-aiops — governed Kubernetes operations for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, prompt-injection sanitize) is
+bundled under ``k8s_aiops.governance`` — this package has no external
+skill-family dependency. Works with any kubeconfig-reachable cluster
+(standard Kubernetes, k3s, EKS, GKE, AKS). Preview: not yet full-coverage.
+"""
+
+__version__ = "0.1.0"

k8s_aiops-0.1.0/k8s_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for k8s-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``k8s-aiops = "k8s_aiops.cli:app"`` works unchanged.
+"""
+
+from k8s_aiops.cli._root import app
+
+__all__ = ["app"]

k8s_aiops-0.1.0/k8s_aiops/cli/_common.py

@@ -0,0 +1,81 @@
+"""Shared helpers for k8s-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+# ─── Shared Option types ───────────────────────────────────────────────────
+
+TargetOption = Annotated[
+    str | None, typer.Option("--target", "-t", help="Target name from config")
+]
+NamespaceOption = Annotated[
+    str | None, typer.Option("--namespace", "-n", help="Namespace (omit for all/default)")
+]
+DryRunOption = Annotated[
+    bool, typer.Option("--dry-run", help="Print the operation without executing")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback."""
+    from k8s_aiops.connection import K8sApiError
+
+    return (K8sApiError, KeyError, OSError, ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key: {message}"
+            console.print(f"[red]Error: {message}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+def get_connection(target: str | None, config_path: Path | None = None):
+    """Return a (conn, config) tuple for the given target."""
+    from k8s_aiops.config import load_config
+    from k8s_aiops.connection import ConnectionManager
+
+    cfg = load_config(config_path)
+    mgr = ConnectionManager(cfg)
+    return mgr.connect(target), cfg
+
+
+def dry_run_print(*, operation: str, detail: str, parameters: dict | None = None) -> None:
+    """Print a dry-run preview of the operation that would be performed."""
+    console.print("\n[bold magenta][DRY-RUN] No changes will be made.[/]")
+    console.print(f"[magenta]  Operation: {operation}[/]")
+    console.print(f"[magenta]  Detail:    {detail}[/]")
+    for k, v in (parameters or {}).items():
+        console.print(f"[magenta]  Param:     {k} = {v}[/]")
+    console.print("[magenta]  Run without --dry-run to execute.[/]\n")
+
+
+def double_confirm(action: str, resource: str) -> None:
+    """Require two confirmations for a destructive operation."""
+    console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")
+    typer.confirm(f"Confirm 1/2: {action} '{resource}'?", abort=True)
+    typer.confirm(
+        f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
+        abort=True,
+    )

k8s_aiops-0.1.0/k8s_aiops/cli/_root.py

@@ -0,0 +1,78 @@
+"""Top-level Typer app: assembles sub-apps and top-level commands."""
+
+from __future__ import annotations
+
+import typer
+
+from k8s_aiops.cli._common import NamespaceOption, TargetOption, cli_errors
+from k8s_aiops.cli.deployment import deployment_app
+from k8s_aiops.cli.doctor import doctor_cmd
+from k8s_aiops.cli.namespace import namespace_app
+from k8s_aiops.cli.node import node_app
+from k8s_aiops.cli.pod import pod_app
+from k8s_aiops.cli.service import service_app
+
+app = typer.Typer(
+    name="k8s-aiops",
+    help="Governed Kubernetes operations for AI agents (works with k3s/EKS/GKE/AKS).",
+    no_args_is_help=True,
+)
+
+app.add_typer(pod_app, name="pod")
+app.add_typer(deployment_app, name="deployment")
+app.add_typer(service_app, name="service")
+app.add_typer(node_app, name="node")
+app.add_typer(namespace_app, name="namespace")
+app.command("doctor")(doctor_cmd)
+
+
+@app.command("events")
+@cli_errors
+def events_cmd(target: TargetOption = None, namespace: NamespaceOption = None) -> None:
+    """List recent cluster events (namespace-scoped or all-namespaces)."""
+    from rich.console import Console
+    from rich.table import Table
+
+    from k8s_aiops.cli._common import get_connection
+    from k8s_aiops.ops import workloads
+
+    conn, _ = get_connection(target)
+    rows = workloads.list_events(conn, namespace)
+    table = Table(title="Kubernetes Events")
+    for col in ("type", "reason", "object", "namespace", "message", "age"):
+        table.add_column(col)
+    for r in rows:
+        table.add_row(
+            r["type"], r["reason"], r["object"], r["namespace"], r["message"], r["age"]
+        )
+    Console().print(table)
+
+
+@app.command("mcp")
+@cli_errors
+def mcp_cmd() -> None:
+    """Start the MCP server (stdio transport).
+
+    Single-command entry point for MCP clients (does not go through uvx/PyPI
+    resolution at launch):
+        k8s-aiops mcp
+    """
+    import sys
+
+    if sys.version_info < (3, 11):
+        typer.echo(
+            f"ERROR: k8s-aiops requires Python >= 3.11 "
+            f"(got {sys.version_info.major}.{sys.version_info.minor}).\n"
+            f"Fix: uv python install 3.12 && "
+            f"uv tool install --python 3.12 --force k8s-aiops",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    from mcp_server.server import main as _mcp_main
+
+    _mcp_main()
+
+
+if __name__ == "__main__":
+    app()

k8s_aiops-0.1.0/k8s_aiops/cli/deployment.py

@@ -0,0 +1,95 @@
+"""``k8s-aiops deployment ...`` sub-commands."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from k8s_aiops.cli._common import (
+    DryRunOption,
+    NamespaceOption,
+    TargetOption,
+    cli_errors,
+    double_confirm,
+    dry_run_print,
+    get_connection,
+)
+from k8s_aiops.ops import lifecycle, workloads
+
+deployment_app = typer.Typer(help="Deployment operations.", no_args_is_help=True)
+console = Console()
+
+
+@deployment_app.command("list")
+@cli_errors
+def deployment_list(target: TargetOption = None, namespace: NamespaceOption = None) -> None:
+    """List deployments (name, namespace, desired/ready/available, age)."""
+    conn, _ = get_connection(target)
+    rows = workloads.list_deployments(conn, namespace)
+    table = Table(title="Deployments")
+    for col in ("name", "namespace", "desired", "ready", "available", "age"):
+        table.add_column(col)
+    for r in rows:
+        table.add_row(
+            r["name"], r["namespace"], str(r["desired"]),
+            str(r["ready"]), str(r["available"]), r["age"],
+        )
+    console.print(table)
+
+
+@deployment_app.command("get")
+@cli_errors
+def deployment_get(
+    name: str, target: TargetOption = None, namespace: NamespaceOption = None
+) -> None:
+    """Show detail for one deployment."""
+    conn, _ = get_connection(target)
+    for k, v in workloads.get_deployment(conn, name, namespace).items():
+        console.print(f"  [cyan]{k}:[/] {v}")
+
+
+@deployment_app.command("scale")
+@cli_errors
+def deployment_scale(
+    name: str,
+    replicas: int,
+    target: TargetOption = None,
+    namespace: NamespaceOption = None,
+) -> None:
+    """Scale a deployment to a replica count."""
+    conn, _ = get_connection(target)
+    result = lifecycle.scale_deployment(conn, name, replicas, namespace)
+    console.print(
+        f"[green]Scaled {name} -> {replicas}[/] "
+        f"(was {result['previous_replicas']})"
+    )
+
+
+@deployment_app.command("restart")
+@cli_errors
+def deployment_restart(
+    name: str, target: TargetOption = None, namespace: NamespaceOption = None
+) -> None:
+    """Trigger a rolling restart of a deployment."""
+    conn, _ = get_connection(target)
+    lifecycle.rollout_restart_deployment(conn, name, namespace)
+    console.print(f"[green]Rollout restart triggered for {name}[/]")
+
+
+@deployment_app.command("delete")
+@cli_errors
+def deployment_delete(
+    name: str,
+    target: TargetOption = None,
+    namespace: NamespaceOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """Delete a deployment and its pods (HIGH RISK — double confirm)."""
+    if dry_run:
+        dry_run_print(operation="delete_deployment", detail=f"delete deployment {name}")
+        return
+    double_confirm("delete", f"deployment {name}")
+    conn, _ = get_connection(target)
+    lifecycle.delete_deployment(conn, name, namespace)
+    console.print(f"[green]Deleted deployment {name}[/]")

k8s_aiops-0.1.0/k8s_aiops/cli/doctor.py

@@ -0,0 +1,21 @@
+"""Doctor top-level command: environment and connectivity check."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from k8s_aiops.cli._common import cli_errors
+
+
+@cli_errors
+def doctor_cmd(
+    skip_auth: Annotated[
+        bool, typer.Option("--skip-auth", help="Skip connectivity check (faster)")
+    ] = False,
+) -> None:
+    """Check config and cluster reachability."""
+    from k8s_aiops.doctor import run_doctor
+
+    raise typer.Exit(run_doctor(skip_auth=skip_auth))

k8s_aiops-0.1.0/k8s_aiops/cli/namespace.py

@@ -0,0 +1,27 @@
+"""``k8s-aiops namespace ...`` sub-commands."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from k8s_aiops.cli._common import TargetOption, cli_errors, get_connection
+from k8s_aiops.ops import namespaces
+
+namespace_app = typer.Typer(help="Namespace operations.", no_args_is_help=True)
+console = Console()
+
+
+@namespace_app.command("list")
+@cli_errors
+def namespace_list(target: TargetOption = None) -> None:
+    """List namespaces (name, phase, age)."""
+    conn, _ = get_connection(target)
+    rows = namespaces.list_namespaces(conn)
+    table = Table(title="Namespaces")
+    for col in ("name", "phase", "age"):
+        table.add_column(col)
+    for r in rows:
+        table.add_row(r["name"], r["phase"], r["age"])
+    console.print(table)