LangGraph K8s Agent

Agent Kubernetes piloté par LLM (Ollama + DeepSeek) construit avec LangGraph. Il observe votre cluster, propose/planifie des actions et peut appliquer des remédiations automatiques via un moteur de règles simple.

Fonctionnalités

• Observation et raisonnement via LLM (DeepSeek local avec Ollama)
• Auto-healing minimaliste via src/healing/:
  • Règles déclaratives (Rule)
  • Registre d’actions (ActionRegistry)
  • Cooldowns pour éviter les boucles
  • Moteur d’évaluation (HealingEngine)
• Intégration K8s: utilise votre ~/.kube/config (monté en read-only)
• Mode API (optionnel) et intégrations monitoring (Prometheus/Grafana en profils)

Architecture (aperçu)

langgraph-k8s-agent/
├─ src/
│  ├─ agent/
│  │  ├─ __init__.py
│  │  ├─ state.py            # `AgentState` utilisé par le graphe
│  │  ├─ core.py             # logique coeur de l'agent (noeuds LangGraph)
│  │  └─ prompts.py          # prompts pour le LLM
│  └─ healing/
│     ├─ __init__.py         # exporte l'API publique
│     ├─ actions.py          # `HealingAction`, `ActionRegistry`, `global_registry`
│     ├─ cooldown.py         # `CooldownStore`, `global_cooldowns`
│     ├─ rules.py            # `Rule`
│     └─ engine.py           # `HealingEngine`
├─ docker-compose.yml
├─ Dockerfile
├─ config/
├─ data/
└─ logs/

Prérequis

• Python 3.12 ou supérieur
• Ollama installé et fonctionnel
• Accès à un cluster Kubernetes (kubeconfig local fonctionnel)
• Minimum 8GB RAM pour faire tourner les modèles LLM

Installation

1. Installer Ollama :

curl -fsSL https://ollama.ai/install.sh | sh

2. Démarrer le serveur Ollama :

ollama serve

3. Télécharger le modèle LLM (dans un autre terminal) :

# Option 1 : Modèle léger (recommandé pour débuter)
ollama pull mistral:latest

# Option 2 : Modèle plus performant
ollama pull deepseek-chat

4. Créer et activer un environnement virtuel Python :

python -m venv venv
source venv/bin/activate  # Linux/macOS
# ou
.\venv\Scripts\activate  # Windows

5. Installer les dépendances :

pip install -r requirements.txt

Démarrage rapide

1. S'assurer que votre cluster Kubernetes est accessible :

kubectl cluster-info
kubectl get nodes

2. Démarrer l'agent en mode debug :

./scripts/run_debug.sh

3. Tester l'agent (dans un autre terminal) :

curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"query":"Vérifie les pods et détecte CrashLoopBackOff","namespace":"default","trigger_healing":true}'

Dépannage

Erreur de connexion à Ollama

Si vous obtenez une erreur de type "Connection refused" :

1. Vérifiez que Ollama tourne bien :

curl http://localhost:11434
# Devrait répondre "Ollama is running"

2. Vérifiez que le modèle est installé :

ollama list
# Devrait lister vos modèles installés

Erreur de connexion à Kubernetes

Si l'agent ne peut pas se connecter au cluster :

1. Vérifiez votre configuration kubectl :

kubectl config view --minify

2. Testez l'accès au cluster :

kubectl get nodes

3. Pour minikube, assurez-vous qu'il est démarré :

minikube status

Variables d'environnement

• OLLAMA_BASE_URL : URL du serveur Ollama (défaut: http://localhost:11434)
• OLLAMA_MODEL : Modèle à utiliser (défaut: mistral:latest)
• KUBECONFIG : Chemin vers votre fichier kubeconfig (défaut: ~/.kube/config)
• LOG_LEVEL : Niveau de log (défaut: INFO)

- Le service `ollama` expose `http://localhost:11434`.
- Le service `ollama-setup` télécharge le modèle `deepseek-r1:latest` dans le volume partagé.
- L’agent démarre ensuite (`k8s-agent`) avec `python main.py` (modifiable).

2) Suivre les logs de l’agent:

```bash
docker compose logs -f k8s-agent

3. Arrêter:

docker compose down

Configuration (variables d’environnement principales)

Définies dans docker-compose.yml pour le service k8s-agent:

• LLM
  • OLLAMA_BASE_URL (défaut http://ollama:11434)
  • OLLAMA_MODEL (défaut deepseek-r1:latest)
• Agent
  • AUTO_HEALING_ENABLED (true/false)
  • CHECK_INTERVAL (secondes entre vérifications, ex: 30)
  • NAMESPACES (liste séparée par des virgules, ex: default,kube-system)
• Kubernetes
  • KUBECONFIG (défaut /home/app/.kube/config, monté depuis ~/.kube/config)
• Logging
  • LOG_LEVEL (DEBUG/INFO/WARN/ERROR)
  • LOG_FORMAT (json/text)
• API (optionnel)
  • API_ENABLED (true/false)
  • API_PORT (ex: 8000)
• Notifications (optionnel)
  • SLACK_WEBHOOK_URL
  • DISCORD_WEBHOOK_URL

Services additionnels activables par profils:

• prometheus (profil monitoring) -> port 9090
• grafana (profil monitoring) -> port 3000 (admin/admin par défaut)
• postgres (profil database) -> port 5432

Exemples:

# Activer monitoring
docker compose --profile monitoring up -d

# Activer base de données
docker compose --profile database up -d

Utilisation Avancée

Configuration des règles de healing

Les règles de healing sont définies dans config/healing_rules.yaml :

rules:
  - name: "restart_crashloopbackoff"
    description: "Redémarre les pods en CrashLoopBackOff"
    conditions:
      - "pod.status.phase == 'Failed'"
      - "pod.status.containerStatuses[*].state.waiting.reason == 'CrashLoopBackOff'"
    actions:
      - "restart_deployment"
    cooldown: 300  # 5 minutes entre les actions

API REST

L'agent expose une API REST sur le port 8000 :

# Vérification de santé
curl http://localhost:8000/health

# Analyse du cluster
curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"query":"Vérifie les pods et détecte CrashLoopBackOff","namespace":"default"}'

# Déclencher une réparation
curl -X POST http://localhost:8000/healing \
  -H "Content-Type: application/json" \
  -d '{"context":{"namespace":"default","pod":"app-xyz-123"}}'

Monitoring

L'agent expose des métriques Prometheus sur /metrics :

• k8s_agent_analyses_total : Nombre total d'analyses effectuées
• k8s_agent_healing_actions_total : Nombre d'actions de réparation
• k8s_agent_errors_total : Nombre d'erreurs rencontrées

Logging

Les logs sont écrits dans logs/api.log en mode debug. Pour ajuster le niveau :

export LOG_LEVEL=DEBUG  # ou INFO, WARNING, ERROR
./scripts/run_debug.sh

Tests d'Intégration

Pour tester avec un cluster local :

# Démarrer minikube
minikube start

# Déployer une application de test
kubectl apply -f tests/fixtures/test-app.yaml

# Simuler une erreur
kubectl scale deployment test-app --replicas=0

Contributing

Voir CONTRIBUTING.md pour les guidelines de contribution.

Les composants clés sont dans src/healing/.

• Rule dans src/healing/rules.py
• ActionRegistry et HealingAction dans src/healing/actions.py
• CooldownStore dans src/healing/cooldown.py
• HealingEngine dans src/healing/engine.py

Exemple minimal:

from healing import Rule, HealingEngine, global_registry

# 1) Déclarer une action

def redemarrer_service(context):
    service = context.get("service", "unknown")
    print(f"[healing] restart {service}")

global_registry.register("restart_service", redemarrer_service)

# 2) Définir une règle

def service_down(context):
    return context.get("status") == "down"

rules = [
    Rule(
        name="restart_when_down",
        when=service_down,
        action="restart_service",
        cooldown_seconds=60.0,   # évite les boucles
        cooldown_key="svc:api", # identifiant de cooldown (optionnel)
    )
]

# 3) Évaluer
engine = HealingEngine(rules)
executed = engine.evaluate({"status": "down", "service": "api"})
print(executed)  # ["restart_when_down"] si exécutée

Intégration dans votre graphe LangGraph:

• Construire un context: Dict[str, Any] (ex: métriques, événements K8s, erreurs, état).
• Appeler HealingEngine.evaluate(context) depuis un nœud dédié.
• Contrôler la fréquence via cooldown_seconds et cooldown_key.

Développement

• Le code source est monté dans le conteneur (./src:/app/src) pour un feedback rapide.
• Adapter la commande de démarrage de l’agent dans docker-compose.yml (ex: python api.py).
• Ajouter vos intégrations k8s, parsers de métriques, et actions concrètes (kubectl/SDK) dans src/.

Tests rapides locaux (hors Docker):

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt  # si présent
python -c "from healing import *; print('healing ok')"

Sécurité & bonnes pratiques

• Ne jamais commiter de secrets. Utiliser des variables d’environnement / stores sécurisés.
• Gérer les actions de remédiation avec prudence (dry-run, approvals, cooldowns).
• Limiter la portée RBAC du compte utilisé par l’agent.

Licence

MIT (sauf mention contraire). Voir LICENSE si présent.