Overview
Un LLM ne lance pas spontanément une commande dans votre cluster Kubernetes. Il produit une réponse. Pour transformer cette réponse en action, un programme doit l’interpréter, décider comment l’exécuter, récupérer le résultat et organiser le tour suivant.
Le harness est cette couche d’exécution et de contrôle autour du modèle. Dans ce lab, il relie un ticket d’incident, un modèle, des outils de diagnostic, des observations et une condition d’arrêt. Le dépôt propose cinq configurations, de A-kubectl à E-observability, autour d’une même panne Kubernetes (source : README du lab).
La vidéo associée est disponible ici : Harness : c’est quoi ? Démos simples.
Cet article repose sur la lecture du dépôt et des documentations officielles. Le lab n’a pas été exécuté pour cette rédaction et la transcription de la vidéo n’était pas accessible. Les sorties décrites sont donc des comportements prévus par le code, pas des mesures issues d’un test ni une restitution du contenu oral.
Objectif
L’objectif est de comprendre ce qui change quand on garde un même problème et un même modèle par défaut, mais que l’on modifie leur environnement d’exécution.
Le ticket demande à l’agent de diagnostiquer l’inaccessibilité du Service HTTP checkout, dans le namespace xh-service, sur le port 80. Il doit citer deux observations et proposer une correction sans l’appliquer (source : script du mode A).
La panne est volontaire :
- deux pods portent les labels
app=checkoutettrack=stable; - le Service sélectionne
app=checkoutettrack=canary; - le script de préparation attend que les pods soient prêts et vérifie que le Service n’a aucune destination.
La question n’est donc pas seulement « le modèle connaît-il Kubernetes ? », mais aussi « quelles observations lui donne-t-on et quelles actions le programme autorise-t-il ? » (sources : manifest de l’incident, script de reset).
Liens utiles
- Dépôt du lab : 02-demo-harness
- Vidéo associée
- README de mini-SWE-agent
- Site et documentation de mini-SWE-agent
- Release mini-SWE-agent v2.4.6
- Documentation Ollama
- Dépôt OpenSandbox
- Site et documentation OpenSandbox
- Documentation Kubernetes : Services
- Documentation kind
Installation
Préparer les dépendances
Le README du lab demande Docker et Ollama démarrés, kubectl et Python 3.13. Un binaire kind destiné au Mac de préparation est fourni dans cluster/.bin/. Sur une autre architecture, il faut le remplacer par un binaire compatible ; le dépôt ne constitue donc pas une installation universelle prête à lancer sur tout poste (source : README).
Depuis le répertoire 02-demo-harness :
python3.13 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
ollama pull qwen3:8b
Le fichier requirements.txt fixe mini-swe-agent==2.4.6. La release correspondante documente notamment une correction du comptage des appels facturés qui échouent au parsing vis-à-vis de cost_limit ; ce n’est pas une garantie de coût pour ce lab (sources : requirements.txt, release v2.4.6).
Si le serveur Ollama n’est pas déjà actif, le README indique de lancer dans un autre terminal :
ollama serve
Les cinq modes utilisent par défaut ollama_chat/qwen3:8b et acceptent la variable LAB_MODEL. Ollama fournit ici le service d’inférence local ; il n’organise pas lui-même les lectures Kubernetes ni la politique des commandes du lab (sources : README, documentation Ollama).
Ajouter OpenSandbox pour les modes D et E
Le lab fixe également la version du SDK :
.venv/bin/python -m pip install opensandbox==1.2.1
Le script de démarrage utilise uvx et épingle le serveur en version 1.2.1. Il faut donc aussi disposer de uv. Les documentations actuelles d’OpenSandbox présentent des possibilités plus larges que ce scénario ; pour reproduire le lab, conserver ses scripts et ses versions plutôt que mélanger des exemples issus de versions différentes (sources : script opensandbox.sh, README OpenSandbox).
Notions et concepts
Modèle, outil et harness : trois responsabilités différentes
Dans le lab, le modèle lit le ticket et les observations précédentes, puis produit un bloc Markdown bash. Le programme extrait la commande de ce bloc. L’environnement d’exécution la traite et renvoie une observation au modèle.
Le déroulement peut se résumer ainsi :
Ticket + instructions
↓
Modèle
↓
Action demandée
↓
Harness / environnement → contrôle et exécution
↓
Observation
↓
Nouveau tour du modèle ou arrêt
Ce schéma décrit le lab, pas une norme imposée à tous les agents. mini-SWE-agent documente justement une approche avec commandes textuelles, historique linéaire et exécution d’actions, sans exiger l’interface native de tool calling du modèle (sources : code du mode A, documentation mini-SWE-agent).
Les cinq variantes
| Mode | Interface de diagnostic | Ce qui change |
|---|---|---|
| A — kubectl | Commandes shell et kubectl | Le modèle choisit les commandes de lecture. |
| B — skill | Même interface, avec une méthode de diagnostic | Des instructions supplémentaires guident l’enquête. |
| C — harness | Quatre commandes de collecte autorisées | Le code refuse les autres demandes d’investigation. |
| D — OpenSandbox | Mêmes vues que C | Le collecteur s’exécute dans une sandbox dédiée. |
| E — observabilité | Même enquête que D | L’opérateur voit les logs et des échantillons CPU/mémoire. |
Les modes A et B ne sont pas « sans harness » : ils ont déjà une boucle d’agent et un environnement d’exécution. Le nom C-harness désigne ici une variante dont la politique et les observations sont davantage spécialisées (source : README du lab).
Un skill guide ; une politique impose
Le mode B ajoute un fichier SKILL.md demandant d’identifier le périmètre, d’observer les ressources, de formuler une hypothèse et de rechercher les éléments qui la distinguent d’autres causes possibles. Dans ce lab, le skill est du texte ajouté aux instructions, pas un mécanisme autonome de permissions (source : skill du mode B).
Le mode C introduit une contrainte différente. Son code accepte exactement quatre demandes d’investigation :
investigate
investigate --service
investigate --pods
investigate --endpoints
La commande spéciale report permet de soumettre le diagnostic et de terminer. Une autre demande d’investigation reçoit une réponse de refus. Les noms ressemblent à des commandes shell, mais investigate est ici une interface traitée par le programme : ce n’est pas un utilitaire à installer sur le poste (source : collecteur et politique C).
Demander au modèle de rester en lecture seule et empêcher une écriture sont deux choses différentes. Le lab utilise aussi un compte Kubernetes limité par RBAC : les droits portent sur des lectures dans xh-service, sans permission de modifier le Service (source : configuration RBAC).
Les observations font partie de la conception
Le collecteur C ne renvoie pas simplement tous les objets Kubernetes en JSON. Il expose les ports et le selector du Service, regroupe les pods par readiness et labels pertinents, puis compte les EndpointSlices et les adresses prêtes.
Cette synthèse organise l’information que le modèle peut utiliser. Elle ne suffit cependant pas à démontrer une réduction de tokens ou une amélioration du diagnostic : ces effets doivent être mesurés sur des runs (source : collecteur C).
Côté Kubernetes, le mécanisme sous-jacent est documenté : un Service avec selector cible les pods qui correspondent à ses labels, et le control plane ajuste les EndpointSlices associés. Des pods prêts ne prouvent donc pas qu’un Service les sélectionne (source : documentation Services).
La sandbox ne remplace ni les permissions ni le contrôle réseau
A et B exécutent déjà les commandes dans un conteneur Docker avec credentials de lecture, système de fichiers en lecture seule, /tmp temporaire et capacités supprimées. D ne représente donc pas le passage d’une exécution sans isolation à une exécution isolée : il introduit une intégration OpenSandbox et un cycle de vie dédié au collecteur (source : environnement des modes shell).
OpenSandbox fournit des API de création, d’exécution et de destruction d’environnements. Le lab y copie le collecteur, la configuration reader, le certificat CA et le token nécessaires à la lecture de Kubernetes (sources : site OpenSandbox, README du lab).
Les slides précisent les limites du montage : réseau kind partagé, accès latéral potentiellement possible et contrôle local en HTTP avec clé API. Pour une adaptation en production, elles recommandent notamment de refuser le trafic entre pairs par défaut, de n’autoriser que les destinations nécessaires et d’utiliser HTTPS pour les endpoints distants (source : slides du lab).
Commandes
Toutes les commandes suivantes sont documentées dans le README et s’exécutent depuis la racine du lab.
Attention : reset.sh supprime et recrée le cluster kind nommé tuto-harness-demo. Ne pas y conserver de travail à préserver.
Préparer l’incident et vérifier les droits :
./cluster/reset.sh
./cluster/check.sh
Lancer séparément les trois premiers modes :
.venv/bin/python A-kubectl/run.py
.venv/bin/python B-skill/run.py
.venv/bin/python C-harness/run.py
Recréer l’incident avant chaque variante d’une comparaison :
python3 run.py A B C
Démarrer le serveur OpenSandbox dans un terminal dédié :
./cluster/opensandbox.sh
Puis, avec le cluster préparé, utiliser un second terminal :
.venv/bin/python D-opensandbox/run.py
.venv/bin/python E-observability/run.py
Les comparaisons documentées incluent aussi :
python3 run.py C D
python3 run.py D E
Le lanceur run.py réalise un reset avant chaque mode sélectionné et utilise le Python de .venv pour démarrer l’agent (sources : README, lanceur).
Démo
Le parcours consiste à préparer une panne connue, observer comment les variantes conduisent l’enquête, puis comparer leurs rapports et leurs traces. Il ne s’agit pas de demander à l’agent de réparer le cluster.
Préparation du run
Après installation, démarrer Docker et Ollama, puis lancer ./cluster/reset.sh. Le script recrée le cluster dédié, déploie l’incident, attend les deux pods et vérifie l’absence de destinations pour checkout. Il génère également un token reader frais.
Lancer ensuite ./cluster/check.sh. Le README indique que cette vérification couvre les refus de lecture dans un autre namespace, de lecture à l’échelle du cluster et de mise à jour du Service. Ce contrôle doit précéder l’enquête : il sert à vérifier les droits effectifs plutôt qu’à s’en remettre uniquement aux instructions du modèle (sources : reset.sh, README).
Lancement : comparer A, B et C
Lancer python3 run.py A B C pour rejouer l’incident avant chaque variante.
Dans A, regarder les commandes choisies par le modèle et les données qu’elles rapportent. Dans B, examiner si l’ajout de la méthode de diagnostic modifie cette séquence. Dans C, observer comment l’agent utilise la vue globale et les vues ciblées, et si des demandes sont refusées.
Le diagnostic attendu d’après les manifests est le décalage entre track=canary dans le selector du Service et track=stable sur les pods. Un rapport étayé doit citer des observations réelles du run ; il ne suffit pas de réciter cette cause connue. La correction proposée peut consister à aligner le selector sur les pods stable si ce sont bien les backends voulus. Elle doit rester du texte, sans application automatique (sources : incident.yaml, ticket et instructions).
Lancement dans OpenSandbox
Installer le SDK, démarrer ./cluster/opensandbox.sh dans un terminal dédié, puis utiliser python3 run.py C D dans un autre terminal.
Le README indique que D conserve le modèle, le ticket, le skill et les quatre vues de C. Le collecteur est copié dans une sandbox créée pour l’enquête, puis celle-ci est détruite à la sortie. Cette comparaison permet d’examiner le changement d’environnement d’exécution sans changer simultanément l’interface de diagnostic (source : README).
Suivi : distinguer ce que voit le modèle de ce que voit l’opérateur
Avec E, l’opérateur voit l’identifiant de sandbox, sa création et sa destruction, les commandes exécutées, leur code de retour, leur durée aller-retour, stdout et stderr. Après chaque commande, le programme demande aussi un échantillon CPU/mémoire.
Le modèle continue de recevoir la même observation compacte que dans D. Les logs opérateur vont sur stderr, tandis que le rapport et le résumé du run vont sur stdout. L’observabilité n’est donc pas simplement un ajout de toutes les traces dans le contexte du LLM (sources : sandbox E, README).
Sortie et réutilisation
Chaque mode affiche le diagnostic, le nombre de tours du modèle, les appels d’outils, le temps d’investigation, les tokens d’entrée et de sortie et la séquence de commandes. Un comptage de tokens incomplet apparaît comme n/a (source : README).
Pour exploiter ces données, conserver le rapport et la séquence d’actions de chaque run, puis distinguer :
- la justesse de la cause et des preuves ;
- les lectures utiles, répétées ou refusées ;
- les ressources consommées ;
- le périmètre exact du chronométrage.
Trois précautions sont documentées : le timer de D commence après la création de la sandbox ; les appels SDK supplémentaires de E entrent dans son temps d’investigation ; les échantillons pris après commande peuvent manquer un pic CPU/mémoire. Une demande investigate compte par ailleurs comme un appel d’outil, même si le collecteur effectue plusieurs lectures Kubernetes (source : README).
Enfin, Submitted signale la soumission d’un rapport, pas une validation indépendante de sa justesse. Le code termine avec succès sur ce statut : il faut donc relire le contenu avant d’en faire une mesure de réussite du diagnostic (source : script E).
Conclusion
Ce lab sépare des éléments que l’on regroupe souvent sous le mot « agent » : le modèle propose, le skill guide, les outils collectent, le harness organise et contrôle l’exécution, les permissions limitent l’accès, la sandbox délimite l’environnement et l’observabilité expose le déroulement.
L’enseignement central est concret : une consigne n’est pas une permission, une sandbox n’est pas une politique réseau, et un rapport soumis n’est pas un diagnostic validé. Les cinq variantes permettent d’examiner ces différences sur un incident Kubernetes identique, sans devoir changer de modèle à chaque étape.
Pour reproduire le parcours, commencer par le README et les modes A à C, puis ajouter OpenSandbox et l’observabilité. Les scripts et leurs traces constituent le point de départ pour mesurer les effets de chaque choix, sans présumer du résultat.
Transparence IA
Ce contenu a été partiellement rédigé ou structuré avec l aide d outils d intelligence artificielle, puis relu, corrigé et complété par l auteur avant publication.