How mrankitvish/ai-agent-kubectl works
Project type and purpose
• This is a backend microservice built with FastAPI. Its purpose is to accept natural-language queries, convert them to kubectl commands using the OpenAI API, optionally execute those commands on a Kubernetes cluster, and return results along with timing/validation metadata.
File structure
• Top-level files:
• app.py – the FastAPI application entry point
• requirements.txt – dependencies (FastAPI, OpenAI, cachetools, asyncio, Prometheus client, etc.)
• Dockerfile & docker-compose.yml – containerization and local orchestration
• .env-sample – environment variables (API_AUTH_KEY, OPENAI_API_KEY, RATE_LIMIT, CACHE_TTL)
• No frontend directory; all logic lives in Python modules referenced by app.py (likely in the same folder or imported).
Extract additional insights from README
• Features: command conversion, safety validation, caching (TTLCache), rate limiting, Prometheus metrics
• API: two POST endpoints (/kubectl-command and /execute) with separate request/response schemas
• Architecture section lists five layers:
1. API Layer (FastAPI)
2. Service Layer (business rules)
3. LLM Integration (OpenAI)
4. Caching Layer (TTLCache)
5. Execution Layer (async subprocess)
a. Main components:
• Client (curl/HTTP client or UI)
• API Layer (FastAPI)
• Authentication & Rate Limiter
• Service Layer
• LLM Integration (external OpenAI API)
• Caching Layer (in-memory TTLCache)
• Execution Layer (async subprocess invoking kubectl)
• Metrics & Monitoring (Prometheus client)
• Environment & Config (.env variables)
• Containerization (Docker, docker-compose)
b. Relationships & interactions:
1. Client → API Layer: sends POST /kubectl-command or /execute with API key
2. API Layer → Auth & Rate Limiter: verify X-API-Key, enforce RATE_LIMIT
3. API Layer → Service Layer: route request to generate or execute service
4. Service Layer:
• For generation: check Cache → if miss call LLM Integration → store in Cache
• For execution: validate command safety → call Execution Layer
5. LLM Integration ↔ OpenAI API (HTTPS)
6. Execution Layer → subprocess kubectl → Kubernetes cluster (stdout/stderr)
7. All layers emit metrics → Prometheus registry
8. Docker container runs app with environment from .env
c. Architectural patterns & principles:
• Clean architecture (layered separation)
• Single responsibility: split generate vs execute endpoints
• Externalize configuration via environment variables
• Observable: Prometheus metrics, timing metadata
• Safe fallback: caching to reduce LLM calls, validation before execution
d. Key technologies:
• FastAPI (web framework)
• cachetools.TTLCache (caching)
• Asyncio & subprocess (command execution)
• OpenAI Python SDK (LLM)
• Prometheus client (metrics)
• Docker & docker-compose (deployment)