How blackzu/k8s-troubleshooting-agent works
AI Kubernetes Agent is a web product intended to let users request Kubernetes troubleshooting and view an AI-generated diagnosis. The documented path runs from the Next.js frontend through a FastAPI orchestrator to Kubernetes inspection and AI reasoning. The implementation is still a foundation: the backend currently registers only a health endpoint, while investigation, pod inspection, and cluster reasoning are empty stubs. Dashed links represent the README’s intended workflow, not verified runtime calls; frontend wiring beyond the shown provider setup is not established by the excerpts.
Main entry points: main.py FastAPI app · investigation.py Investigation service · reasoning.py Cluster reasoning · HomePage.tsx Home page
Components 18
Web frontend
- Home page
frontend/components/HomePage.tsx - Investigate control
frontend/components/InvestigateButton.tsx - Health hook
frontend/hooks/useHealth.ts - API client
frontend/services/api.ts - App shell
frontend/app/layout.tsx - Query provider
frontend/app/providers.tsx
Backend service
- FastAPI app
backend/main.py - Health route
backend/api/health.py - Health schema
backend/models/schemas.py - Runtime settings
backend/core/config.py - Logging setup
backend/core/logging.py
Diagnosis capabilities
- Investigation service
backend/services/investigation.py - Pod inspection
backend/kubernetes/pods.py - Cluster reasoning
backend/ai/reasoning.py - Root cause and fix
Other components
- Troubleshooting user
- Kubernetes cluster
- OpenRouter LLM
Connections 17
- Troubleshooting user → Home page: opens
README.md - Home page → Investigate control: offers
README.md - Investigate control → API client: requests investigation
README.md - API client → FastAPI app: calls backend
README.md - FastAPI app → Health route: registers
backend/main.py - FastAPI app → Runtime settings: configures CORS
backend/main.py - FastAPI app → Logging setup: sets up
backend/main.py - Health route → Health schema: returns
backend/api/health.py - App shell → Query provider: wraps children
frontend/app/layout.tsx - FastAPI app → Investigation service: would orchestrate
README.md - Investigation service → Pod inspection: would inspect
README.md - Investigation service → Cluster reasoning: would request analysis
README.md - Pod inspection → Kubernetes cluster: would inspect
README.md - Cluster reasoning → OpenRouter LLM: would use
README.md - Cluster reasoning → Root cause and fix: would produce
README.md - Root cause and fix → Home page: would display
README.md - Health hook → API client: uses