⎈ Agentic K8s AIOps 🤖

An autonomous, AI-powered Kubernetes troubleshooting and remediation agent. This tool continuously monitors your Kubernetes cluster, detects anomalies, and leverages local LLMs (via Ollama) to diagnose and automatically fix issues—all without relying on external cloud APIs.

🌟 Key Features

• 🔍 Automated Cluster Scanning: Detects CrashLoopBackOff, OOMKilled, ImagePullBackOff, and pending pods.

• 🤖 Local AI Diagnosis: Powered by the gemma4:cloud model via Ollama for secure, on-premise AI processing.

• 🛠️ Autonomous Auto-Remediation: Executes kubectl commands directly to resolve detected issues using a ReAct agent framework.

• 💻 Claude Code Native (MCP): Fully integrated Model Context Protocol (MCP) server for terminal-based interactions.

• 🎨 Beautiful Web Dashboard: A sleek, dark-themed UI for visualizing cluster health, viewing AI reasoning, and managing self-healing workflows.

Related MCP server: K8s Warning Monitor MCP

🏗️ Architecture

The platform operates using a modular ReAct (Reasoning and Acting) pattern:

1. Observation: The k8s_scanner.py module continuously polls the cluster for degraded states.

2. Thinking: The ai_agent.py evaluates the issue using the local Ollama LLM.

3. Action: Through the MCP server, the agent executes targeted kubectl commands to remediate the issue.

🚀 Quick Start

Ensure you have Python 3.11+, Ollama, and kubectl configured.

# 1. Clone the repository & setup
git clone https://github.com/yuankraj/agentic-k8s-aiops.git
cd agentic-k8s-aiops
bash setup.sh

# 2. Start the local Ollama server
ollama serve

# 3. Launch the Web Dashboard
source .venv/bin/activate
python app.py

# 4. Open in your browser
# http://localhost:8000

📖 Comprehensive Usage Guide

This agent can be run in three different modes:

1. Web UI Mode (via FastAPI dashboard)

2. Claude Code Native Mode (via FastMCP terminal server)

3. Pure Terminal Chat Mode (via Python script)

👉 Check out the USAGE.md file for detailed step-by-step instructions for all execution modes.

📂 Project Structure

.
├── app.py            # Main web server (FastAPI)
├── mcp_server.py     # FastMCP Server (Claude Code integration)
├── k8s_scanner.py    # Kubernetes cluster scanner for fault detection
├── ai_agent.py       # Ollama ReAct AI agent with auto-fix tools
├── terminal_chat.py  # Pure terminal interaction script
├── setup.sh          # One-click environment configuration
├── requirements.txt  # Python dependencies
└── static/           # Frontend assets (UI, styling, logic)
    ├── index.html    
    ├── style.css     
    └── app.js        

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to open an issue or submit a pull request.

Built with ❤️ for resilient Kubernetes operations.