Résolution des Problèmes de Connectivité des Agents Jenkins : Causes et Solutions

Les agents Jenkins, également appelés nœuds, sont l'endroit où la plupart des travaux de build s'exécutent réellement. Lorsque l'un d'eux devient hors ligne, le symptôme est évident : les travaux restent en file d'attente, les labels ne peuvent pas être satisfaits et les équipes recommencent des builds qui n'auraient jamais dû démarrer. Le travail utile consiste à déterminer quelle couche est défaillante : l'accessibilité réseau, SSH, la communication entrante, Java, les identifiants, le disque ou le contrôleur lui-même.

Comprendre pourquoi un agent peut devenir inaccessible est la première étape pour un dépannage efficace. Ces problèmes peuvent provenir de mauvaises configurations réseau, d'une configuration incorrecte de l'agent, de restrictions de pare-feu ou de problèmes avec le contrôleur Jenkins lui-même. En vérifiant systématiquement ces domaines, vous pouvez rapidement identifier la cause racine et mettre en œuvre une solution.

Causes Courantes de Déconnexion des Agents Jenkins

Plusieurs facteurs peuvent entraîner la mise hors ligne d'un agent. Identifier le symptôme spécifique est essentiel pour réduire les causes potentielles :

Agent inaccessible : Le contrôleur Jenkins ne peut pas établir de connexion avec l'agent.
Connexion refusée : La machine de l'agent rejette activement la tentative de connexion du contrôleur.
L'agent signale qu'il est hors ligne après une connexion réussie : L'agent était connecté mais a depuis perdu sa connexion.
Erreurs JSch (pour les agents basés sur SSH) : Erreurs spécifiques liées à la bibliothèque Java Secure Channel utilisée pour les connexions SSH.

Problèmes de Réseau et de Pare-feu

La connectivité réseau est la cause la plus fréquente des problèmes de connexion des agents. Il est primordial de s'assurer que le contrôleur Jenkins peut atteindre la machine de l'agent et vice-versa.

Vérification de l'Accessibilité Réseau

Avant de plonger dans les configurations spécifiques à Jenkins, confirmez la connectivité réseau de base :

Ping sur l'agent : Depuis la machine du contrôleur Jenkins, essayez de pinguer l'adresse IP ou le nom d'hôte de la machine de l'agent.
```
ping <nom-hote-ou-ip-agent>
```
Telnet vers le port de l'agent : Testez si le port que Jenkins utilise pour se connecter à l'agent est ouvert et à l'écoute. Pour les agents JNLP, il s'agit généralement du port 50000. Pour les agents SSH, c'est le port SSH (par défaut 22).
```
telnet <nom-hote-ou-ip-agent> <port-agent>
```
Si la connexion expire ou est refusée, il y a probablement un problème de réseau ou de pare-feu bloquant le port.

Configuration du Pare-feu

Les pare-feu, que ce soit sur le contrôleur Jenkins, la machine de l'agent ou des périphériques réseau intermédiaires, peuvent bloquer les ports nécessaires.

Pare-feu du Contrôleur Jenkins : Assurez-vous que le contrôleur peut initier des connexions vers le port de l'agent.
Pare-feu de la Machine de l'Agent : Assurez-vous que le pare-feu de la machine de l'agent (par exemple, ufw, firewalld, le pare-feu Windows) autorise les connexions entrantes sur le port de l'agent depuis l'adresse IP du contrôleur Jenkins.
Pare-feux Réseau : Si votre réseau dispose de pare-feux internes, vérifiez que le trafic est autorisé entre le contrôleur et l'agent.

Exemple : Autoriser le Port 50000 sur un Agent (Linux avec `ufw`)

# Autoriser les connexions depuis une IP spécifique (contrôleur Jenkins)
sudo ufw allow from <ip-controleur-jenkins> to any port 50000

# Ou autoriser depuis n'importe quelle IP (moins sécurisé)
sudo ufw allow 50000

# Recharger les règles du pare-feu
sudo ufw reload

Exemple : Autoriser le Port 22 sur un Agent (Linux avec `firewalld`)

# Autoriser le service SSH de manière permanente depuis une IP source spécifique
sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="<ip-controleur-jenkins>" port protocol="tcp" port="22" accept'

# Recharger les règles du pare-feu
sudo firewall-cmd --reload

Astuce : Privilégiez toujours l'autorisation des connexions depuis des adresses IP spécifiques pour une meilleure sécurité.

Problèmes de Configuration des Agents Jenkins

Les mauvaises configurations dans Jenkins ou sur l'agent lui-même sont des sources courantes de problèmes de connectivité.

Configuration de l'Agent JNLP

Les agents Java Network Launch Protocol (JNLP) communiquent avec le contrôleur Jenkins en utilisant un port dédié. La configuration principale implique la méthode de lancement de l'agent et les ports disponibles du contrôleur.

L'Agent est Hors Ligne dans l'Interface Jenkins

Si un agent apparaît hors ligne dans l'interface Jenkins, cela signifie que le contrôleur n'a pas pu établir ou maintenir une connexion.

Vérifiez la Méthode de Lancement de l'Agent : Assurez-vous que l'agent est configuré pour se lancer correctement. Les méthodes courantes incluent :
- Lancer l'agent en le connectant au maître : Cela nécessite une initiation manuelle du côté de l'agent.
- Lancer l'agent via SSH : Configuré via les identifiants SSH et les paramètres d'hôte.
- Lancer l'agent en utilisant les propriétés intégrées du nœud : Pour des scénarios spécifiques.
Vérifiez la Disponibilité du Port JNLP : Le contrôleur Jenkins doit écouter sur le port JNLP configuré (par défaut 50000). Accédez à Gérer Jenkins -> Système -> Avancé -> Fichier -> Port TCP pour les agents JNLP et assurez-vous qu'il est défini et accessible.

"Connexion refusée" lors du Lancement de l'Agent JNLP

Cela signifie souvent que le port JNLP (par défaut 50000) sur le contrôleur Jenkins n'est pas ouvert ou accessible depuis la machine de l'agent. Vérifiez les règles de pare-feu sur le contrôleur et assurez-vous que le port est correctement configuré.

Astuce : Redémarrer le contrôleur Jenkins peut parfois résoudre des problèmes transitoires de port JNLP.

Configuration de l'Agent SSH

Lors de l'utilisation de SSH pour se connecter aux agents, plusieurs facteurs peuvent causer des problèmes :

Identifiants SSH Incorrects : Vérifiez le nom d'utilisateur, le mot de passe ou la clé privée configurés dans Jenkins pour la connexion SSH. Assurez-vous que la clé privée est correctement formatée (par exemple, format PEM) et a les bonnes permissions.
Serveur SSH Non Exécuté sur l'Agent : Assurez-vous que le démon SSH (sshd) est en cours d'exécution sur la machine de l'agent.
```
# Sur la machine de l'agent
sudo systemctl status sshd
# ou
sudo service ssh status
```
S'il n'est pas en cours d'exécution, démarrez-le :
```
sudo systemctl start sshd
sudo systemctl enable sshd
```
Décalage de Port SSH : Assurez-vous que le port configuré dans Jenkins pour SSH correspond au port sur lequel le serveur SSH écoute (par défaut 22).
Résolution du Nom d'Hôte/IP de l'Agent : Le contrôleur Jenkins doit pouvoir résoudre le nom d'hôte ou l'adresse IP de l'agent.
Permissions de la Clé SSH : Sur la machine de l'agent, le fichier ~/.ssh/authorized_keys pour l'utilisateur auquel Jenkins se connecte doit avoir les bonnes permissions (généralement 600).

Exemple : Tester la Connexion SSH Manuellement

Depuis la machine du contrôleur Jenkins, essayez de vous connecter en SSH à l'agent en utilisant les mêmes identifiants et le même port que ceux configurés dans Jenkins :

ssh -p <port-ssh> <utilisateur-jenkins>@<nom-hote-ou-ip-agent>

Si cette commande SSH manuelle échoue, le problème se situe en dehors de la configuration SSH de Jenkins, probablement dans les paramètres réseau, de pare-feu ou du serveur SSH sur l'agent.

Permissions du Répertoire de Travail de l'Agent

Jenkins nécessite des permissions spécifiques pour fonctionner sur le système de fichiers de l'agent. L'utilisateur que Jenkins utilise pour se connecter à l'agent (ou l'utilisateur exécutant le processus de l'agent) a besoin de permissions d'écriture sur le répertoire de travail configuré de l'agent.

Vérifiez le propriétaire et les permissions : Sur l'agent, vérifiez la propriété et les permissions du répertoire personnel de Jenkins et de ses sous-répertoires.
```
ls -ld /chemin/vers/repertoire/agent/jenkins
ls -l /chemin/vers/repertoire/agent/jenkins
```
Accordez les permissions (si nécessaire) : Assurez-vous que l'utilisateur auquel Jenkins se connecte a un accès en lecture et en écriture. Utilisez chown et chmod avec précaution.

Problèmes du Contrôleur Jenkins

Parfois, le problème peut ne pas provenir de l'agent mais du contrôleur Jenkins lui-même.

Surcharge du Contrôleur

Si le contrôleur Jenkins est sous forte charge (nombreux travaux en cours d'exécution, utilisation élevée du CPU/mémoire), il peut avoir du mal à gérer les connexions des agents. Surveillez l'utilisation des ressources du contrôleur.

Conflits de Port JNLP

Si le port JNLP (par défaut 50000) est déjà utilisé par un autre processus sur le contrôleur Jenkins, les agents ne pourront pas se connecter.

Vérifiez l'utilisation du port : Sur la machine du contrôleur, utilisez netstat ou ss pour voir quel processus utilise le port.
```
sudo netstat -tulnp | grep 50000
# ou
sudo ss -tulnp | grep 50000
```
Si un autre processus l'utilise, vous devrez reconfigurer Jenkins ou l'autre application pour utiliser des ports différents.

Dépannage Avancé et Journaux

Lorsque les vérifications standard ne révèlent pas le problème, une enquête plus approfondie est nécessaire.

Journaux du Contrôleur Jenkins

Consultez les journaux du contrôleur Jenkins pour les erreurs liées aux connexions des agents. Ces journaux peuvent fournir des messages d'erreur spécifiques.

Emplacement : Généralement dans $JENKINS_HOME/jenkins.log ou accessible via Gérer Jenkins -> Journal Système.
Recherchez : Des messages mentionnant le nom d'hôte de l'agent, l'adresse IP, les tentatives de connexion, les exceptions JSch ou les erreurs de Connexion refusée.

Journaux de l'Agent

Si l'agent est en cours d'exécution mais signale qu'il est hors ligne, vérifiez ses journaux pour toute erreur.

Agents JNLP : Le processus de l'agent lui-même peut générer des journaux sur sa console ou dans un fichier journal désigné.
Agents SSH : Les journaux peuvent se trouver dans $JENKINS_HOME/agent.log sur la machine de l'agent, ou être liés à sshd si la connexion échoue au niveau SSH.

Activer la Journalisation de Débogage

Pour des problèmes très persistants, l'activation temporaire de la journalisation de débogage pour les composants Jenkins concernés peut fournir des informations plus granulaires.

Communication JNLP/Agent : Vous devrez peut-être ajuster les propriétés système Java ou utiliser la configuration de journalisation de Jenkins (Gérer Jenkins -> Journal Système -> Enregistreurs de Journal) pour augmenter la verbosité pour hudson.slaves ou les packages associés.

Habitudes Pratiques pour Prévenir les Pannes Récurrentes

Le dépannage de la connectivité des agents Jenkins nécessite une approche systématique, en commençant par les vérifications réseau de base et en progressant vers les configurations spécifiques à Jenkins.

Vérifiez le Réseau : Commencez toujours par un ping et telnet/nc pour garantir l'accessibilité réseau de base et l'accès au port.
Vérifiez les Pare-feux : Assurez-vous que les pare-feux sur le contrôleur et l'agent, ainsi que les pare-feux réseau, autorisent le trafic sur les ports requis.
Validez les Identifiants : Revérifiez les clés SSH, les noms d'utilisateur et les mots de passe.
Confirmez le Service de l'Agent : Pour les agents SSH, assurez-vous que sshd est en cours d'exécution et accessible.
Surveillez les Journaux Jenkins : Les journaux du contrôleur sont votre source principale pour comprendre les échecs de connexion.
Utilisez des IP Spécifiques : Dans la mesure du possible, configurez les pare-feux et Jenkins pour utiliser des adresses IP spécifiques plutôt que des plages larges ou 0.0.0.0.

En suivant ces étapes, vous pouvez diagnostiquer et résoudre efficacement la plupart des problèmes courants de connectivité des agents Jenkins, en maintenant vos pipelines CI/CD opérationnels.

Lire le Message Hors Ligne Sans Deviner

Le mot "hors ligne" est trop large pour être dépanné seul. Avant de modifier les paramètres Jenkins, ouvrez la page de l'agent et lisez la raison exacte donnée par Jenkins. Il y a une grande différence entre "connexion refusée", "permission refusée", "vérification de la clé d'hôte échouée", "agent JNLP rejeté" et "canal fermé". Ils se terminent tous par un nœud hors ligne, mais ils pointent vers différentes couches.

J'écris généralement le symptôme en langage clair : "le contrôleur ne peut pas atteindre le port TCP 22", "la connexion SSH fonctionne mais Java ne peut pas démarrer", "l'agent entrant démarre mais ne peut pas rappeler le contrôleur" ou "l'agent se connecte puis se déconnecte pendant les builds". Cette seule phrase permet de garder l'investigation ciblée.

Si l'agent ne s'est jamais connecté, suspectez la configuration, le DNS, le pare-feu, les identifiants ou la commande de lancement. S'il s'est connecté pendant des mois et a commencé à échouer aujourd'hui, vérifiez les changements récents : clés SSH tournées, mise à niveau de Jenkins, mise à jour d'un plugin, nouvelle règle de pare-feu, certificat expiré, reconstruction de l'image de l'agent ou modification de la configuration réseau cloud. La chronologie est souvent plus utile que le texte d'erreur.

Agents SSH : Séparez les Problèmes de Connexion des Problèmes de Lancement

Pour les agents basés sur SSH, testez le même chemin que Jenkins utilise. Depuis l'hôte du contrôleur, connectez-vous en tant qu'utilisateur configuré par Jenkins :

ssh -vvv utilisateur-agent-jenkins@nom-hote-agent

La sortie verbose vous indique si l'échec se produit avant l'authentification, pendant l'authentification ou après la connexion. Si SSH n'atteint jamais le serveur, Jenkins ne peut pas résoudre cela. Vérifiez le routage, les groupes de sécurité, les ACL réseau, les pare-feux de l'hôte et le démon SSH. Si SSH atteint le serveur mais rejette la clé, vérifiez l'identifiant dans Jenkins, le fichier authorized_keys de l'utilisateur, les permissions des fichiers et si le compte est verrouillé.

Si la connexion SSH fonctionne manuellement mais que Jenkins échoue toujours, regardez le répertoire racine distant et le démarrage Java. Jenkins a besoin d'un répertoire inscriptible pour les fichiers de communication à distance, et l'utilisateur de l'agent a besoin de l'autorisation de créer des fichiers là-bas. Une erreur courante consiste à pointer la racine distante vers un chemin appartenant à root ou nettoyé par un autre processus.

Effectuez ces vérifications sur l'agent :

whoami
pwd
java -version
test -w /chemin/vers/agent-jenkins && echo inscriptible
df -h /chemin/vers/agent-jenkins

La version de Java est importante car les contrôleurs Jenkins modernes nécessitent des versions Java compatibles sur les agents. L'exigence exacte dépend de votre version de Jenkins, alors consultez la documentation Jenkins pour votre version au lieu de supposer qu'une ancienne image d'agent est toujours valide.

Agents Entrants : Le Chemin de Rappel est le Piège Habituel

Les agents entrants sont souvent utilisés lorsque le contrôleur ne peut pas initier SSH vers l'agent, par exemple pour les agents derrière un NAT ou dans des réseaux restreints. Le processus de l'agent démarre en dehors de Jenkins et se reconnecte au contrôleur. Cela signifie que le chemin réseau est inversé : l'agent doit résoudre et atteindre l'URL Jenkins.

Sur l'hôte de l'agent, testez l'URL Jenkins exactement comme configurée :

curl -I https://jenkins.example.com/

Si Jenkins est derrière un proxy inverse, confirmez que l'URL publique dans Gérer Jenkins > Système est correcte. Une URL Jenkins erronée peut faire pointer les commandes d'agent générées vers un nom d'hôte interne que l'agent ne peut pas résoudre. Si le mode WebSocket est activé pour les agents entrants, assurez-vous que le proxy prend en charge les en-têtes de mise à niveau WebSocket. Si vous utilisez le port TCP entrant de l'agent à la place, confirmez que le port fixe est configuré et accessible depuis le réseau de l'agent.

Les problèmes TLS peuvent ressembler à des problèmes Jenkins. Si l'agent s'exécute dans une image conteneur minimale, il peut ne pas avoir votre certificat CA interne. curl le révélera généralement rapidement. Installez le certificat CA dans l'image de l'agent plutôt que de désactiver la vérification du certificat.

Agents qui se Déconnectent Pendant les Builds

Un agent qui se connecte avec succès puis se déconnecte pendant un build n'est généralement pas un problème de connectivité de base. Vérifiez la pression sur les ressources et le cycle de vie du processus.

Vérifiez si le système d'exploitation a tué le processus de l'agent :

dmesg -T | grep -i -E 'killed process|out of memory'
journalctl -u jenkins-agent --since '2 hours ago'

Vérifiez également l'espace disque. La communication à distance Jenkins, l'extraction, les rapports de test et les artefacts archivés ont tous besoin d'espace. Un volume d'espace de travail plein peut rendre un agent peu fiable car le processus de communication à distance ne peut pas écrire de fichiers temporaires ou de journaux.

Si les déconnexions se produisent lors de sorties console volumineuses, d'archivage d'artefacts ou de publication de rapports de test, examinez la stabilité du réseau et la charge du contrôleur. Le canal de l'agent est une connexion en direct. Les longues pauses de garbage collection sur le contrôleur, les proxys surchargés, les délais d'attente de connexion inactive et la perte de paquets peuvent tous le fermer. Pour les agents traversant des équilibreurs de charge ou des proxys d'entreprise, vérifiez les paramètres de délai d'attente d'inactivité et le comportement de maintien de la connexion.

Problèmes de DNS et de Clé d'Hôte

Les changements DNS sont faciles à manquer. Jenkins peut se connecter à build-agent-01, tandis que votre test manuel utilise une adresse IP. Testez le nom d'hôte depuis le contrôleur :

getent hosts build-agent-01
nc -vz build-agent-01 22

Si le nom d'hôte se résout en une adresse incorrecte, corrigez le DNS ou la configuration de l'agent. Évitez les correctifs à long terme de /etc/hosts à moins d'avoir un processus de propriété clair, car ils deviennent une infrastructure invisible.

Pour les agents SSH, la vérification de la clé d'hôte protège Jenkins contre la connexion à une machine inattendue. Si un agent a été reconstruit, sa clé d'hôte peut avoir changé. Ne désactivez pas aveuglément la vérification. Confirmez la reconstruction, supprimez l'ancienne clé du fichier known_hosts de l'utilisateur du contrôleur et acceptez la nouvelle clé via la stratégie Jenkins configurée.

Une Liste de Vérification de Récupération pour les Agents de Production

Lorsque plusieurs agents deviennent hors ligne en même temps, évitez de les réparer un par un avant de trouver la cause commune. Demandez :

Le contrôleur Jenkins a-t-il redémarré ou été mis à niveau ?
Un identifiant partagé a-t-il été tourné ?
Une image de base d'agent a-t-elle changé ?
Un changement de pare-feu, proxy, VPN ou DNS a-t-il été déployé ?
Tous les agents en échec sont-ils dans le même sous-réseau, compte cloud, espace de noms Kubernetes ou zone de disponibilité ?

Si un seul agent échoue, inspectez cet hôte. Si tout un groupe échoue ensemble, inspectez la dépendance commune. Cela fait gagner beaucoup de temps dans les grandes flottes Jenkins.