k8agent — Kubernetes Natural-Language Agent (MVP)

k8agent is a read-only, session-safe CLI tool designed to help you interactively diagnose and query your Kubernetes clusters in natural language. It uses a LangGraph ReAct agent and LangChain to interface with Kubernetes clusters.

Features

• Secure Session-Only Credentials: LLM keys and configurations are held strictly in memory.
• Strict Read-Only Access: Never modifies cluster state (no delete, apply, patch, scale, etc.).
• Namespace Allowed List: Restricts the LLM agent to a user-approved set of namespaces.
• Evidence-Gathering Agent: Calls tools in sequence (e.g. list pods -> check logs) before coming to a conclusion.

1. Quick Start

Prerequisites

• Python 3.11+
• A working Kubernetes context configured in ~/.kube/config

Installation

Clone the repository and install the dependencies:

# Initialize a virtual environment
python -m venv .venv
.\.venv\Scripts\activate

# Install the package in editable mode
pip install -e .[dev]

Starting the REPL

k8agent
# Or alternatively
python -m k8agent.cli

2. Configuring RBAC (Recommended Security Boundary)

To restrict the agent to read-only actions and specific namespaces, apply the provided template.

1. Customize the template: Open k8s/rbac-template.yaml and replace {{NAMESPACE}} with the namespace you wish to grant access to (e.g. default).

2. Apply the template:

   kubectl apply -f k8s/rbac-template.yaml
   

3. Generate Kubeconfig for the ServiceAccount: Use the following commands to create a temporary token and generate a dedicated kubeconfig context pointing to this ServiceAccount:

   # Create a token for the ServiceAccount
   kubectl create token k8agent-sa --namespace=<YOUR_NAMESPACE>
   

   You can then configure this token in a separate kubeconfig file to guarantee the cluster-side RBAC boundary.

3. Tool Reference

The agent has access to the following explicit list of tools:

• list_allowed_namespaces: Get the namespace scope of the current session.
• list_pods: Get names, status, and restart counts.
• describe_pod: Get detailed container statuses and conditions.
• get_pod_logs: Retrieve container logs (supports tail_lines and previous).
• list_deployments: View desired vs ready replicas.
• describe_deployment: View rolling status and conditions.
• list_services: View type, cluster IP, and ports.
• list_events: View recent events sorted by last-seen.
• list_configmaps: View names and keys only.
• get_node_status: View node names and cluster resource conditions (cluster-scoped).

4. Running Tests

To run unit tests against a mocked Kubernetes API:

pytest tests/

5. Publishing to PyPI

To build and upload the package to PyPI so it can be installed globally via pip:

1. Install build tools:

   pip install build twine
   

2. Build the source and binary wheels:

   python -m build
   

   This generates .tar.gz and .whl files in the dist/ directory.

3. Upload to PyPI:

   python -m twine upload dist/*