KS-AI: AI-Powered Kubernetes Operations Assistant

KS-AI is a production-grade AI assistant that brings natural language understanding to Kubernetes operations. Ask questions in plain English, get intelligent responses with real-time cluster insights.

---

Why KS-AI?

Traditional K8s Management	With KS-AI
kubectl get pods -n app -o wide | grep -v Running	"Show me unhealthy pods in the app namespace"
Multiple commands + manual analysis	Single natural language query
Requires memorizing kubectl syntax	Just describe what you need
No context awareness	Understands your cluster state

Key Differentiators

• Natural Language Interface - No more memorizing kubectl flags and YAML syntax
• Real-time Cluster Awareness - AI queries your actual cluster, not just documentation
• Production-Safe - Built-in guardrails prevent destructive operations without confirmation
• Multi-Model Fallback - Automatic failover between Gemini models on rate limits
• Beautiful TUI - Full-featured terminal interface with animations

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         KS-AI System                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
│  │   Go TUI    │───▶│   FastAPI   │───▶│   MCP Server        │ │
│  │  (ks-ai)    │    │   Backend   │    │  (K8s Tools)        │ │
│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
│        │                  │                      │              │
│        │                  ▼                      ▼              │
│        │           ┌─────────────┐    ┌─────────────────────┐  │
│        │           │  Gemini AI  │    │  Kubernetes API     │  │
│        │           │  (+ Fallback│    │  (kubectl/client)   │  │
│        │           │   Models)   │    └─────────────────────┘  │
│        │           └─────────────┘                              │
│        │                                                        │
│        └─────────── Server-Sent Events (SSE) ◀──────────────────│
│                     (Real-time Streaming)                       │
└─────────────────────────────────────────────────────────────────┘

---

Features

1. Intelligent Terminal UI (TUI)

Built with Bubble Tea, the TUI provides:

• Split-Pane View - Chat on left, command logs on right
• Resizable Panes - Ctrl+←/→ to adjust widths
• Mouse Support - Scroll with mouse wheel, click to focus
• Keyboard Navigation - Full vim-style and arrow key support
• Real-time Streaming - Watch AI responses appear character by character
• Syntax Highlighting - kubectl commands are color-coded
• Animated Elements - Walking cat 🐱, loading spinner

2. MCP Server (Model Context Protocol)

Exposes Kubernetes operations as AI-callable tools:

Tool	Description
list_namespaces	Get all namespaces
list_pods	List pods with status, restarts, age
list_deployments	Deployment details and replica status
list_services	Service types, ports, selectors
get_pod_logs	Retrieve container logs
describe_resource	Detailed resource information
apply_manifest	Apply YAML configurations
delete_resource	Remove resources (with confirmation)
scale_deployment	Adjust replica counts
get_cluster_info	Cluster version and health

3. Resilient AI Backend

• Multi-Model Fallback - Cycles through models on rate limits:

  gemini-2.5-pro → gemini-2.0-flash → gemini-2.0-flash-lite → gemini-1.5-flash
  

• Automatic Retry - Exponential backoff with smart delay parsing
• Rate Limiting - 500ms minimum between API calls
• Conversation History - Maintains context (last 20 messages)

4. Production Safety

• Destructive Operation Warnings - Delete/scale operations require confirmation
• Namespace Isolation - Operations scoped to current namespace by default
• Audit Logging - All kubectl commands logged to file
• Error Recovery - Graceful handling of cluster connectivity issues

---

Quick Start

Prerequisites

• Go 1.21+ - For TUI binary
• Python 3.10+ - For backend and MCP server
• kubectl - Configured with cluster access
• Gemini API Key - From Google AI Studio

Installation

# Clone repository
git clone https://github.com/Ayushpani/ks-ai.git
cd ks-ai

# Set up Python environment
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure API key
cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY

# Build TUI
cd cmd/ks-ai && go build -o ../../ks-ai && cd ../..

Running

# Terminal 1: Start MCP Server
make mcp-server

# Terminal 2: Start Backend  
make backend

# Terminal 3: Launch TUI
./ks-ai

Or use the combined command:

make dev  # Starts all services

---

Usage Examples

Basic Queries

> List all pods in default namespace
> Show me deployments that are not fully available
> What services are exposed externally?
> Get logs from the nginx pod

Troubleshooting

> Why is my pod crashing?
> Show pods with high restart counts
> What's consuming the most memory?
> Are there any pending pods?

Operations

> Scale the web deployment to 5 replicas
> Describe the redis service
> Get events from the api namespace
> Show me the YAML for deployment/app

---

Keyboard Shortcuts

Key	Action
Enter	Send message
Tab	Switch between Chat/Log panes
↑/↓	Scroll content
Ctrl+U/D	Page up/down
Ctrl+←/→	Resize panes
Ctrl+Y	Copy chat to clipboard
Ctrl+L	Clear conversation history
F1	Toggle help menu
Ctrl+C	Exit

---

Configuration

Environment Variables

Variable	Description	Default
GOOGLE_API_KEY	Gemini API key	Required
GEMINI_MODEL	Primary model	gemini-2.5-flash
MCP_SERVER_URL	MCP server endpoint	http://localhost:8000/sse
BACKEND_PORT	Backend API port	8080

Fallback Models

Edit app/backend/app/services/gemini_service.py:

FALLBACK_MODELS = [
    'gemini-2.5-pro',
    'gemini-2.0-flash',
    'gemini-2.0-flash-lite',
    'gemini-1.5-flash',
]

---

Project Structure

ks-ai/
├── cmd/ks-ai/           # Go TUI application
│   └── main.go          # TUI entry point
├── internal/tui/        # TUI components
│   ├── mcp_client.go    # Backend API client
│   └── markdown.go      # Markdown rendering
├── app/
│   ├── backend/         # FastAPI backend
│   │   └── app/
│   │       ├── api/     # REST endpoints
│   │       └── services/# Gemini, Chat services
│   └── frontend/        # React web UI (optional)
├── k8s_mcp_server.py    # MCP server with K8s tools
├── mcp_client.py        # Python MCP client
└── Makefile             # Build commands

---

Why This Matters

For Developers

• Faster debugging - Get instant insights without constructing complex queries
• Lower barrier - New team members can operate clusters immediately
• Context retention - AI remembers your conversation for follow-ups

For SREs/DevOps

• Incident response - Quickly assess cluster state during outages
• Audit trail - All commands logged for compliance
• Safety guardrails - Prevent accidental damage

For Teams

• Knowledge democratization - Not everyone needs to be a kubectl expert
• Consistent operations - AI follows best practices
• Documentation on demand - Ask "why" and get explanations

---

Contributing

Contributions welcome! Areas of interest:

• Additional K8s tools (CRDs, Helm, etc.)
• Support for other AI providers (Claude, OpenAI)
• Web UI improvements
• Multi-cluster support

---

License

MIT License - See LICENSE for details.

---

Acknowledgments

• Bubble Tea - TUI framework
• Google Gemini - AI models
• FastMCP - MCP implementation
• Kubernetes Python Client

---

Built with ❤️ for the Kubernetes community