Kubernetes AI Interaction Gateway (k8s-ai-bridge-server)

This utility establishes a robust Model Context Protocol (MCP) endpoint specifically tailored for interfacing with Kubernetes clusters. It translates abstract, intention-based requests from large language models (LLMs) into precise, verifiable kubectl operations, fundamentally bridging the gap between human intent and container orchestration.

📺 Demonstrations: AI Assistants Controlling K8s via the Bridge

See how agents interact with cluster state:

• Watch an interaction with a major LLM agent...
• See Cursor orchestrating deployments...
• Observe Windsurf managing networking resources...

Feature Matrix

Cluster Resource Management (kubectl Equivalents)

• [x] Comprehensive CRUD operations across standard resources (Pods, Services, Deployments, etc.).
• [x] Retrieval of diagnostic artifacts: events, detailed logs, and resource definitions.
• [x] Advanced utility functions: port-forwarding, scaling (Deployments/StatefulSets), and exec into containers.
• [x] Configuration artifact handling: ConfigMaps and Secrets lifecycle management.
• [x] Full support for GitOps integration via Helm charts (install, upgrade, teardown).
• [x] Contextual awareness: Retains namespace state across conversational turns and supports context switching.

AI / Intent Translation Layer

• [x] High-fidelity translation of conversational prompts into executable K8s API calls.
• [x] Memory module for maintaining state and dependency tracking across sequential requests.
• [x] Semantic explanation generation for complex K8s objects or operational outcomes.
• [x] Intelligent tool selection based on user intent, defaulting to raw kubectl invocation if no specialized tool matches.
• [x] Namespace context automatically inferred or explicitly requested.
• [x] Offline simulation capabilities using simulated cluster responses.

Observability and Health

• [x] Real-time surveillance of cluster health and node resource consumption.
• [x] Detailed tracking of container readiness/liveness probe outcomes.
• [x] Utilization of kubectl top for resource metrics acquisition.
• [x] Event stream monitoring for anomaly detection and alerting.
• [x] Historical performance logging and analysis.

Security Posture Assessment

• [x] Auditing of Role-Based Access Control (RBAC) bindings and service account permissions.
• [x] Evaluation of Pod Security Context configurations against best practices.
• [x] Secure handling and isolation of API credentials.
• [x] Network Policy conformance checking.
• [x] Automated identification of insecure defaults.

Troubleshooting and Diagnostics

• [x] Automated root cause analysis for common operational failures.
• [x] Validation checks against declared resource manifests for configuration drift.
• [x] Proactive identification of resource bottlenecks (CPU/Memory limits).
• [x] Detailed analysis of container startup failures (e.g., probe timeouts).

Extensibility and Transport

• [x] Support for various transport mechanisms (e.g., standard I/O streams, Server-Sent Events).
• [x] Framework designed for easy integration of new, specialized operational tools.
• [x] Native handling of Custom Resource Definitions (CRDs).
• [x] Efficient batch processing for bulk resource modifications.

System Architecture Overview

MCP Integration Framework

The core of this service leverages the Model Context Protocol (MCP) specification to provide a standardized communication channel to external LLM systems. The architecture is layered:

1. MCP Endpoint: The primary server component, built using a specialized SDK, ensuring broad compatibility across client applications.
2. Tool Registry: A dynamic catalog mapping high-level AI requests to executable Python functions that interface with the K8s API.
3. Communication Fabric: Handles data exchange using reliable protocols (e.g., JSON-over-Stream).
4. K8s Abstraction Layer: Responsible for securely executing calls against the Kubernetes API server.
5. Response Standardization: Ensures all output conforms strictly to the required MCP response schema.

Operational Modes

The binary supports two distinct operational patterns:

1. Interactive CLI: Used for direct, immediate execution of cluster management tasks from the terminal.
2. Daemon Server: Initiates an MCP listener, waiting for asynchronous requests from integrated AI assistants.

Deployment and Setup

Detailed setup documentation is located in the Development Guide.

Installation via the Python Package Index (PyPI) is the recommended path:

bash pip install k8s-ai-bridge

To fetch a specific version:

bash pip install k8s-ai-bridge==2.0.0

Access the package details here: PyPI Project Page

Prerequisites for Operation

• Python interpreter version 3.10 or newer.
• The kubectl command-line utility must be accessible in the system PATH.
• Authenticated network access to the target Kubernetes cluster.
• The Python dependency manager (pip).

Standard Installation

bash

Install the latest stable release

pip install k8s-ai-bridge

Alternatively, install the cutting-edge version directly from the repository

pip install git+https://github.com/your-org/k8s-ai-bridge-server.git

Local Development Setup

bash

Clone the source repository

git clone https://github.com/your-org/k8s-ai-bridge-server.git cd k8s-ai-bridge-server

Install in editable/development mode

pip install -e .

Verifying Functionality

Confirm the server is operational and correctly configured:

bash k8s-ai-bridge --diagnose

Crucial Note: This tool is primarily engineered as an MCP server. The main execution method is initiating the server process via k8s-ai-bridge serve.

Containerized Deployment

A production-ready, multi-architecture Docker image is hosted on Docker Hub:

bash

Obtain the latest build

docker pull yourrepo/k8s-ai-bridge-server:latest

Running the Server via Docker

The internal service exposes the MCP interface on port 8000. You must map a host port and provide the Kubeconfig file:

bash

Map host port 9090 to container port 8000

Mount your KUBECONFIG file so the container can authenticate to the cluster

docker run -d --name k8s-server -p 9090:8000 \ -v $HOME/.kube/config:/mnt/config/kubeconfig:ro \ yourrepo/k8s-ai-bridge-server:latest

• -p 9090:8000: Host accessibility on 9090.
• -v ...: Provides credentials. The server will be configured to use this path via an environment variable.

Building for Heterogeneous Architectures (Multi-Arch)

Use Docker Buildx to create a manifest supporting both AMD64 and ARM64 platforms:

bash

Setup Buildx environment if necessary

docker buildx create --name multiarch --use

docker buildx inspect --bootstrap

Build and push combined image

docker buildx build --platform linux/amd64,linux/arm64 -t yourrepo/k8s-ai-bridge-server:latest --push .

Configuration Parameters

The MCP server requires specific access controls, particularly concerning Kubernetes configuration files. This is typically managed via container volumes or environment settings.

yaml

Example configuration snippet for orchestration platforms (e.g., Terraform, Helm)

run: volumes: - '{{k8s-ai-bridge-server.kubeconfig_path}}:/access/kubeconfig' config: description: Defines parameters required for the MCP agent to establish cluster connectivity. parameters: type: object properties: kubeconfig_path: type: string description: The absolute path where the kubeconfig file is mounted inside the container. default: /access/kubeconfig required: - kubeconfig_path

This setup explicitly grants the server read-only access to the necessary authentication materials.

Integration Guide for AI Clients

Executing the MCP Bridge

The k8s-ai-bridge.mcp_server module, powered by the FastAPI-based FastMCP framework, ensures high-throughput, standards-compliant communication.

Troubleshooting Note: If unexpected connection behavior occurs, you can temporarily switch the AI client configuration to use k8s-ai-bridge.basic_listener instead. The basic listener offers reduced functionality but isolates potential protocol implementation issues.

1. Generic Client Configuration (e.g., Custom Tooling)

   { "mcpServices": { "clusterOps": { "launcher": "python", "invocation": ["-m", "k8s_ai_bridge.mcp_server"], "environment": { "KUBECONFIG_SOURCE": "/path/to/your/.kube/config", "EXECUTION_LOG_PATH": "/var/log/agent/debug.log", "VERBOSE_MODE": "True", "MCP_SESSION_TIMEOUT": "300" } } } }

2. Key Environment Variables for Fine-Tuning

   • EXECUTION_LOG_PATH: Directs detailed operational logs away from stdout.
   • VERBOSE_MODE: Enables detailed logging (True/False).
   • MCP_SESSION_TIMEOUT: Sets the maximum duration for an active agent session (seconds).
   • KUBECONFIG_SOURCE: Specifies the location of the configuration file.
   • K8S_LOG_LEVEL: Controls verbosity: TRACE, INFO, WARNING, CRITICAL.

3. Connectivity Check (Health Test) Verify the server is listening and responsive using a simple health check utility: bash python -m k8s_ai_bridge.health_check

   This performs a minimal connection handshake.

Client-Specific Integration Snippets

Claude Desktop (Configuration File: claude_desktop_config.json)

{ "mcpServices": { "clusterOps": { "launcher": "python", "invocation": ["-m", "k8s_ai_bridge.mcp_server"], "environment": { "KUBECONFIG_SOURCE": "$HOME/.kube/config" } } } }

Cursor AI (Global MCP Settings: ~/.cursor/mcp.json)

{ "mcpServices": { "clusterOps": { "launcher": "python", "invocation": ["-m", "k8s_ai_bridge.mcp_server"], "environment": { "KUBECONFIG_SOURCE": "/srv/k8s/prod-cluster.yaml", "EXECUTION_PATH_HINTS": "/usr/bin:/opt/homebrew/bin" } } } }

Windsurf Agent (Configuration File: ~/.config/windsurf/mcp.json)

{ "mcpServices": { "clusterOps": { "launcher": "python", "invocation": ["-m", "k8s_ai_bridge.mcp_server"], "environment": { "KUBECONFIG_SOURCE": "/path/to/your/.kube/config" } } } }

Remember to substitute placeholder paths (/path/to/your/.kube/config) with the actual location accessible to the running process.

Automated Client Configuration

For streamlined setup across supported assistants, utilize the provided setup script:

bash ./deploy/configure_clients.sh

This script attempts to inject the necessary server command details into the configuration files of recognized AI tools.