Azure DevOps : diagnostiquer un agent auto-hébergé hors ligne avant de le recréer

Un agent Azure DevOps auto-hébergé qui passe hors ligne déclenche souvent une réaction simple : redémarrer la VM, supprimer l’agent du pool ou recréer un runner propre. Cela peut débloquer un pipeline, mais cela efface aussi les preuves. Si le problème vient d’un token expiré, d’un proxy, d’un disque saturé, d’une identité qui n’accède plus aux dépôts, d’un service systemd arrêté ou d’une route sortante cassée, recréer l’agent ne corrige pas la cause.

Le cas d’usage est courant : une équipe déploie en production avec des agents auto-hébergés placés dans un réseau privé Azure. Les jobs restent en file d’attente, l’agent apparaît offline ou online mais n’accepte plus de travail, et une livraison urgente attend. Le runbook doit décider s’il faut relancer le service, vider un cache, corriger le réseau, réautoriser l’agent, basculer vers un pool de secours ou rollbacker le dernier changement d’infrastructure.

Figurer l’incident comme un contrat

Avant de toucher au runner, il faut nommer le périmètre. Un agent hors ligne n’est pas un symptôme assez précis : le pool peut être indisponible, un seul agent peut être dégradé, un type de job peut échouer, ou l’organisation Azure DevOps peut refuser l’authentification.

Incident a qualifier
Organisation: naxaya-devops
Pool: prod-private-linux
Agent: ado-prod-agent-03
Host: vm-ado-agent-03
Symptomes:
  - agent offline depuis 09:42
  - jobs de deploiement en queue
  - dernier job termine: deploy-api-prod #1842
Changement recent:
  - rotation image VM hier soir
  - nouvelle route sortante vers firewall

Decision attendue
Relancer le service agent
Corriger disque/cache/reseau/identite
Basculer vers pool de secours
Recreer l'agent seulement si les preuves sont conservees

Cette formulation évite de confondre vitesse et diagnostic. Elle permet aussi de communiquer clairement avec l’équipe produit : le pipeline n’est pas seulement lent, il attend une capacité d’exécution privée qui doit être restaurée ou remplacée.

Lire l’état côté Azure DevOps

Le premier contrôle se fait côté service : le pool voit-il l’agent, depuis quand, avec quelle version, quelles demandes système et quelles capacités ? Un agent online peut rester inutilisable si les demandes du job ne correspondent plus à ses capabilities. Un agent offline peut simplement avoir perdu sa session longue durée.

Controles Azure DevOps
Pool cible et files d'attente actives
Agent online/offline et dernier contact
Version agent et update pending
Capabilities exposees par l'agent
Demands utilisees par le pipeline
Jobs recents sur le meme agent
Jobs recents sur les autres agents du pool

Si tous les agents du pool sont offline, le problème ressemble à un incident réseau, proxy, DNS ou organisation. Si un seul agent est touché, le diagnostic se concentre sur l’hôte, le service local, le disque, le cache ou l’identité de runtime.

Vérifier le service local avant de nettoyer

Sur l’hôte, l’objectif n’est pas de redémarrer tout de suite. Il faut d’abord capturer l’état. Le service peut être arrêté, bloqué dans une boucle de reconnexion, incapable de lire son répertoire de travail ou coincé après une mise à jour partielle.

sudo systemctl status vsts.agent.* --no-pager
sudo journalctl -u 'vsts.agent.*' --since '2 hours ago' --no-pager
ps aux | grep '[A]gent.Listener'
df -h
find /opt/azdo-agent/_diag -type f -mtime -1 -maxdepth 1 -print

Les fichiers _diag sont souvent plus utiles qu’un redémarrage immédiat. Ils indiquent si l’agent n’arrive plus à joindre Azure DevOps, s’il refuse un job, s’il échoue pendant la préparation du workspace ou s’il rencontre une erreur d’authentification.

Séparer réseau sortant, proxy et DNS

Un agent privé a presque toujours besoin de sortir vers Azure DevOps, des registres d’artefacts, un repository, un Key Vault, un registry container ou un endpoint de sécurité. Une UDR, un proxy, une règle firewall ou une résolution DNS peuvent suffire à le rendre offline.

Chemin sortant a valider
DNS utilise par l'agent
Proxy configure dans .env, systemd ou variables shell
Route effective depuis la NIC
Regles firewall pour dev.azure.com et dependances
Inspection TLS ou certificat entreprise
Acces aux registries et feeds utilises par les jobs

Preuves utiles
resolution DNS depuis l'hote
curl avec code HTTP et temps de connexion
logs firewall sur l'IP source de l'agent
comparaison avec un agent sain du meme pool

Le bon test n’est pas seulement de joindre Internet. Il faut tester les endpoints réellement utilisés par le runner et par le job. Un agent peut rester online mais échouer dès qu’il doit récupérer un artefact, tirer une image ou lire un secret.

Contrôler identité et secrets de runner

L’agent Azure DevOps utilise un enregistrement dans le pool et un mécanisme d’authentification. Les jobs, eux, utilisent souvent d’autres identités : service connection, managed identity, fédération OIDC, clé de feed, token de registry. Il faut donc distinguer l’identité du runner et l’identité du déploiement.

Identite runner
Permet a l'agent de se connecter au pool Azure DevOps
Peut etre cassee par token expire, reconfiguration ou suppression pool

Identite job
Permet au pipeline de deploier, lire Key Vault, pousser une image ou appeler Azure
Peut etre cassee par RBAC, federation OIDC, secret rotation ou policy

Decision
Ne pas recreer l'agent si seul le job est refuse
Ne pas elargir RBAC si seul le runner est offline

Cette séparation évite deux erreurs opposées : recréer l’agent alors qu’une service connection est cassée, ou élargir les droits Azure alors que le runner ne s’enregistre même plus dans le pool.

Lire disque, workspace et cache sans tout supprimer

Les agents auto-hébergés accumulent workspaces, outils, caches npm, Docker layers, dépôts et artefacts temporaires. Un disque plein peut rendre l’agent instable, mais un nettoyage brutal peut aussi masquer le job qui a saturé l’hôte.

df -h
sudo du -xh /opt/azdo-agent/_work --max-depth=2 | sort -h | tail -20
sudo du -xh /var/lib/docker --max-depth=1 2>/dev/null | sort -h | tail -10
sudo find /opt/azdo-agent/_work -maxdepth 2 -mtime -1 -type d -print | head

La correction doit être ciblée : supprimer les workspaces anciens, purger un cache Docker documenté, augmenter le disque si la charge a changé, ou déplacer certains artefacts. Si l’agent manque régulièrement d’espace, le rollback ne consiste pas à nettoyer une fois, mais à revenir sur le job ou l’image qui a introduit la dérive.

Décider entre relance, bascule et recréation

Une fois les preuves collectées, la décision doit être explicite. Redémarrer le service est acceptable si l’agent a perdu sa session mais que le disque, le réseau et l’identité sont sains. Basculer vers un pool de secours est préférable si l’incident bloque une livraison urgente et que le pool alternatif a les mêmes contrôles. Recréer l’agent est une action de dernier recours si l’enregistrement local est corrompu ou si l’image doit être reconstruite.

Relancer le service
Service bloque, logs captures, reseau OK, disque OK

Nettoyer ou agrandir
Disque sature, cause identifiee, jobs impactes connus

Corriger reseau
DNS, proxy, route ou firewall prouves par logs

Basculer vers pool de secours
Urgence production, pool secours valide, secrets et demands compatibles

Recreer l'agent
Enregistrement corrompu, image non conforme, preuves conservees, ancien agent retire proprement

Chaque option doit avoir une validation : job de diagnostic court, pipeline non destructif, récupération d’artefact, accès Key Vault si nécessaire, puis seulement ensuite reprise du déploiement de production.

Préparer le rollback

Le rollback dépend de la cause. Si une UDR récente a coupé la sortie, on revient à la route précédente. Si une image VM a cassé le service, on réactive l’image précédente ou on remplace par un agent connu sain. Si un nettoyage cache a supprimé un outil requis, on relance l’installation contrôlée au lieu de bricoler sur l’hôte.

Rollback minimal
Reseau: restaurer route/proxy/firewall precedent
Image: revenir au scale set ou template precedent
Agent: retirer l'agent corrompu du pool apres sauvegarde _diag
Pipeline: remettre demands ou pool precedent
Identite: restaurer service connection ou federation validee

Validation apres rollback
Agent online dans le pool
Job de diagnostic termine
Acces artefacts et secrets confirme
Aucun job production relance sans approbation

Conclusion

Un agent Azure DevOps auto-hébergé hors ligne n’est pas seulement un composant à recréer. C’est une capacité d’exécution privée qui dépend d’un service local, d’un pool, d’un réseau sortant, d’un disque, d’un cache et de plusieurs identités. Le runbook utile conserve les preuves, sépare runner et job, teste le chemin réel et choisit une action réversible.

La bonne décision n’est pas toujours la plus spectaculaire. Si le service peut être relancé avec des logs propres, relancez-le. Si la route sortante est cassée, rollbackez la route. Si l’image est mauvaise, remplacez l’agent par une version connue. Recréer le runner devient alors une décision documentée, pas un réflexe qui efface l’incident.