A clean, enterprise-ready AI agent for troubleshooting Kubernetes and Istio issues. Designed to be LLM-agnostic and work with your internal infrastructure.
- Contributing Guide – How to contribute to the project
- Changelog – Version history and release notes
- Local Setup & Examples – Example configs and scripts for running with HuggingFace and other LLMs locally
git clone <repository>
cd k8s-istio-agent
pip install -r requirements.txt# Check system requirements for HuggingFace
python huggingface_example.py --check
# Create configuration
cp config.yaml.example config.yaml
# Edit config.yaml with your LLM provider settings# Interactive CLI
python main.py interactive
# Single query
python main.py query "My pods are not starting"
# Web interface
python main.py web┌─────────────────────────────────────────┐
│ User Interface │
│ (CLI, Web UI, API, Slack Bot) │
└─────────────┬───────────────────────────┘
│
┌─────────────▼───────────────────────────┐
│ Agent Controller │
│ (Task routing, context management) │
└─────────────┬───────────────────────────┘
│
┌─────────────▼──────────────────────────┐
│ LLM Abstraction Layer │
│ (Provider-agnostic interface) │
└───┬─────────┬─────────┬─────────┬──────┘
│ │ │ │
┌───▼───┐ ┌───▼────┐ ┌──▼───┐ ┌───▼──────┐
│OpenAI │ │Hugging │ │Azure │ │ Internal │
│ API │ │ Face │ │OpenAI│ │ Wrappers │
└───────┘ └────────┘ └──────┘ └──────────┘
┌─────────────────────────────────────────┐
│ Tool Registry │
│ (Kubernetes, Istio, Observability) │
└─────────────┬───────────────────────────┘
│
┌─────────────▼───────────────────────────┐
│ Execution Engine │
│ (Safe command execution, context) │
└─────────────────────────────────────────┘
llm:
provider: "huggingface"
config:
model_name: "microsoft/DialoGPT-medium"
device: "auto"
load_in_8bit: true # Memory optimization
max_length: 1024
temperature: 0.7llm:
provider: "openai"
config:
api_key: "${OPENAI_API_KEY}"
model: "gpt-4"llm:
provider: "azure"
config:
azure_endpoint: "https://your-resource.openai.azure.com/"
api_key: "${AZURE_OPENAI_API_KEY}"
api_version: "2023-12-01-preview"
deployment_name: "gpt-4"llm:
provider: "internal"
config:
endpoint: "https://internal-llm.company.com"
api_key: "${INTERNAL_API_KEY}"
model: "company-gpt-4"- kubectl: Safe kubectl commands (get, describe, logs, etc.)
- logs: Advanced log analysis with pattern matching
- resources: Resource usage and health monitoring
- istio_proxy: Proxy status and configuration analysis
- istio_config: Configuration validation and analysis
- traffic: Traffic flow and routing analysis
- prometheus: Metrics querying and analysis
- grafana: Dashboard integration (coming soon)
🤖 What can I help you troubleshoot?
My frontend pods are not starting
🔍 I'll investigate the pod startup issues. Let me check the current status:
kubectl get pods -n frontend
✅ Found pods in ImagePullBackOff status. Let me get more details:
kubectl describe pod frontend-deployment-abc123 -n frontend
🔍 Root cause: Image pull authentication failure
💡 Solution: Configure imagePullSecrets for private registry access
🤖 What can I help you troubleshoot?
Traffic between services is failing intermittently
🔍 Let me check your Istio service mesh configuration:
istio_proxy status
✅ Found stale EDS configuration on backend service
🔍 Checking traffic patterns:
prometheus query 'istio_request_total{destination_service_name="backend"}'
💡 Recommendation: Restart affected pods to refresh Envoy configuration
python main.py interactive --config config_dev.yaml# Build and deploy
docker build -t k8s-istio-agent:latest .
kubectl apply -f k8s/az container create \
--resource-group myResourceGroup \
--name k8s-agent \
--image k8s-istio-agent:latest \
--environment-variables LLM_API_KEY=$API_KEY- RBAC: Minimal required permissions
- Read-only Operations: No destructive commands
- Safe Command Filtering: Whitelist of allowed operations
- Secret Management: Secure credential handling
- Non-root Container: Security-hardened deployment
# 1. User reports issue
user_query = "My application has high latency"
# 2. Agent investigates systematically
agent.process_query(user_query)
# - Checks pod status and resource usage
# - Analyzes application logs for errors
# - Reviews Istio metrics for service mesh issues
# - Examines Prometheus metrics for performance bottlenecks
# 3. Provides actionable recommendations
# - Identifies resource constraints
# - Suggests configuration optimizations
# - Recommends scaling strategies- ✅ No Autogen Dependency: Clean, purpose-built architecture
- ✅ Enterprise Ready: Works with internal LLM wrappers
- ✅ LLM Flexibility: Easy provider swapping
- ✅ Focused Scope: Kubernetes/Istio specific
- ✅ Simple Codebase: Easy to understand and extend
- ✅ Systematic Approach: Follows best practice workflows
- ✅ Knowledge Retention: Learns from patterns
- ✅ Faster Resolution: Automated investigation steps
- ✅ Comprehensive Analysis: Multi-tool correlation
k8s-istio-agent/
├── main.py # Entry point
├── requirements.txt # Dependencies
├── config.yaml # Configuration
├── Dockerfile # Container build
├── llm/ # LLM providers
│ ├── provider.py # Base abstractions
│ └── providers/ # Specific implementations
├── tools/ # Tool system
│ ├── base.py # Tool abstractions
│ ├── registry.py # Tool management
│ ├── kubernetes/ # K8s tools
│ ├── istio/ # Istio tools
│ └── observability/ # Monitoring tools
├── agent/ # Agent logic
│ └── controller.py # Main orchestration
├── web/ # Web interface
│ ├── app.py # FastAPI application
│ └── templates/ # HTML templates
└── k8s/ # Kubernetes manifests
│ ├── deployment.yaml # FastAPI application
│ ├── service.yaml # HTML templates
│ └── rbac.yaml # HTML templates
└── tests/ # Test suite
├── __init__.py # Test package
├── conftest.py # Test configuration
├── unit/ # Unit tests
│ ├── test_llm.py # LLM provider tests
│ ├── test_tools.py # Tool tests
│ └── test_agent.py # Agent logic tests
├── integration/ # Integration tests
│ ├── test_k8s.py # Kubernetes integration
│ ├── test_istio.py # Istio integration
│ └── test_web.py # Web interface tests
└── e2e/ # End-to-end tests
├── test_flows.py # Common workflows
└── test_scenarios.py # Real-world scenarios
llm:
provider: "huggingface"
config:
model_name: "microsoft/DialoGPT-small"
device: "cpu"
torch_dtype: "float32"llm:
provider: "huggingface"
config:
model_name: "microsoft/DialoGPT-medium"
device: "auto"
load_in_8bit: truellm:
provider: "internal"
config:
endpoint: "https://langchain-api.company.com"
api_key: "${COMPANY_LLM_KEY}"az aks create \
--resource-group myResourceGroup \
--name myAKSCluster \
--node-count 3 \
--enable-addons monitoring \
--generate-ssh-keysistioctl install --set values.defaultRevision=default
kubectl label namespace default istio-injection=enabledkubectl apply -f k8s/kubectl port-forward svc/k8s-istio-agent 8080:80 -n troubleshooting
# Open http://localhost:8080- Add New Tools: Extend
tools/directory - New LLM Providers: Add to
llm/providers/ - Enhanced Workflows: Modify
agent/controller.py - UI Improvements: Update
web/components
Create a PR and we will review it.