Diagnostic des problèmes de connectivité Jenkins : Problèmes réseau et d'agent

Jenkins dépend fortement d'une communication robuste entre le contrôleur central et ses environnements d'exécution (Agents ou Nœuds). Lorsque cette connectivité échoue, les builds stagnent, les pipelines s'arrêtent et l'intégration continue s'effondre. Diagnostiquer ces problèmes nécessite une approche systématique, en se concentrant d'abord sur la topologie réseau, puis sur la configuration des agents et les échecs de protocole.

Ce guide complet fournit des instructions étape par étape pour résoudre les problèmes de connectivité Jenkins les plus courants, y compris les problèmes de pare-feu insaisissables, les ports JNLP mal configurés et les échecs de démarrage des agents, vous aidant à restaurer des opérations stables et des pipelines CI/CD fiables rapidement.

---

1. Comprendre la communication Contrôleur-Agent Jenkins

Avant de dépanner, il est essentiel de comprendre comment le contrôleur Jenkins communique avec ses Agents. Jenkins propose deux méthodes principales, chacune avec des exigences de diagnostic uniques :

1.1 Protocole de lancement réseau Java (JNLP)

Dans le modèle JNLP, l'Agent Jenkins initie la connexion au contrôleur. C'est l'approche recommandée et la plus courante. L'Agent se connecte à un port spécifique sur le contrôleur, maintenant communément appelé le port TCP de l'agent entrant.

• Direction : L'agent se connecte au contrôleur.
• Port requis : Le port TCP de l'agent entrant du contrôleur (par défaut souvent 50000, ou attribué dynamiquement).

1.2 Secure Shell (SSH)

Dans le modèle SSH, le contrôleur Jenkins initie la connexion à l'Agent. Cela nécessite que la machine de l'Agent exécute un serveur SSH.

• Direction : Le contrôleur se connecte À l'agent.
• Port requis : Le port SSH de l'agent (généralement 22).
• Exigence : Les identifiants SSH (clés ou mots de passe) doivent être correctement configurés dans Jenkins.

2. Diagnostics réseau et pare-feu initiaux

Les problèmes réseau, en particulier les restrictions de pare-feu, sont la cause la plus fréquente des problèmes de connectivité. Si un agent se déconnecte soudainement ou qu'un nouvel agent ne parvient pas à se connecter, commencez ici.

2.1 Vérifier que les ports requis sont ouverts

Vous devez vous assurer que le trafic peut circuler sur les ports nécessaires en fonction de votre modèle de communication.

Type de connexion	Source	Destination	Port requis	Vérification de l'état
Interface Web	Utilisateur/Agent	Contrôleur	8080 (ou personnalisé)	Accès navigateur
Agent entrant	Agent	Contrôleur	50000 (ou personnalisé)	telnet ou nc
SSH (Contrôleur -> Agent)	Contrôleur	Agent	22 (ou personnalisé)	ssh ou telnet

2.2 Utilisation de Telnet/Netcat pour les tests d'accessibilité

Utilisez telnet ou nc (Netcat) depuis la machine de connexion vers la machine de destination sur le port requis. Une connexion réussie confirme l'accessibilité réseau et qu'aucun pare-feu local ne bloque le port.

Vérification de l'accessibilité de l'agent entrant (de l'agent au contrôleur)

# Remplacez <CONTROLLER_IP> et <JNLP_PORT>
telnet <CONTROLLER_IP> 50000

# Sortie de succès attendue :
# Connected to <CONTROLLER_IP>.
# Escape character is '^]'.

# Sortie d'échec attendue :
# Trying <CONTROLLER_IP>...
# telnet: connect to address <CONTROLLER_IP>: Connection refused

Astuce : Une erreur "Connexion refusée" indique que le chemin réseau est ouvert, mais que le service (Jenkins) n'écoute pas sur ce port, ou qu'un pare-feu local sur le contrôleur le bloque. Si la connexion expire, un pare-feu entre les machines est probablement en cause.

2.3 Définir un port JNLP fixe

Si vous utilisez JNLP, il est recommandé de configurer un port fixe pour éviter toute ambiguïté et simplifier les règles de pare-feu. Jenkins peut utiliser un port d'agent entrant aléatoire à moins que vous ne définissiez un port fixe, ce qui complique les paramètres de sécurité.

1. Accédez à Gérer Jenkins > Sécurité (ou Configurer la sécurité globale sur les anciennes versions de Jenkins).
2. Sous Agents, trouvez l'option pour Port TCP pour les agents entrants.
3. Sélectionnez Fixe et spécifiez un port (par exemple, 50000).
4. Assurez-vous que ce port est ouvert dans le pare-feu du système d'exploitation hôte (par exemple, iptables, firewalld ou le pare-feu Windows) sur la machine du contrôleur.

3. Résolution des problèmes d'agent JNLP

Si les vérifications réseau réussissent, le problème est généralement lié à l'authentification, à la configuration ou à une incompatibilité d'environnement.

3.1 Vérifier les journaux de l'agent sur le contrôleur

Lorsque vous tentez de lancer un agent JNLP, examinez les journaux fournis par Jenkins lui-même. Accédez à la page de configuration spécifique de l'agent et consultez la section Journal. Cela fournit souvent le message d'erreur le plus clair.

• Recherchez les erreurs courantes comme java.net.ConnectException ou hudson.remoting.ChannelClosedException.

3.2 Assurez-vous que les arguments de l'agent sont corrects

Lorsque vous lancez l'agent manuellement à l'aide de la commande fournie par Jenkins (la commande java -jar agent.jar ...), assurez-vous que les paramètres sont corrects.

# Exemple de structure de commande pour le lancement JNLP
java -jar agent.jar -jnlpUrl http://<JENKINS_URL>/computer/<AGENT_NAME>/slave-agent.jnlp -secret <SECRET_TOKEN> -workDir "/path/to/workspace"

• Vérifiez l'URL JNLP : Assurez-vous que l'URL utilise le nom d'hôte et le port corrects du contrôleur. Si Jenkins est derrière un proxy inverse, assurez-vous que la configuration de l'URL Jenkins reflète l'URL externe.
• Vérifiez le jeton secret : Les jetons expirent ou changent si le nœud est reconfiguré. Téléchargez le dernier .jar et utilisez le dernier secret fourni sur la page de lancement de l'agent.

4. Résolution des problèmes d'agent SSH

Si vous utilisez SSH pour lancer des agents, les échecs de connectivité sont généralement dus à des problèmes d'authentification ou d'environnement shell.

4.1 Vérifier la connexion SSH en dehors de Jenkins

Essayez de vous connecter à la machine de l'agent depuis le contrôleur en utilisant le nom d'utilisateur et les identifiants exacts configurés dans Jenkins.

ssh -i /path/to/keyfile jenkins_user@<AGENT_IP>

• Si cela échoue, le problème est environnemental : soit le service SSH est arrêté, soit les identifiants/clés utilisateur sont incorrects, soit les permissions de la clé sont trop permissives (chmod 600 keyfile.pem).

4.2 Vérifier la méthode d'authentification SSH

1. Clés : Assurez-vous que la clé publique correspondant à la clé privée stockée dans le gestionnaire d'identifiants Jenkins est correctement ajoutée au fichier ~/.ssh/authorized_keys de l'utilisateur de l'agent.
2. Mots de passe : Si vous utilisez des mots de passe, assurez-vous que le serveur SSH sur l'agent est configuré pour autoriser l'authentification par mot de passe (déconseillé pour des raisons de sécurité).

4.3 Délai d'attente de lancement de l'agent SSH

Si la connexion SSH réussit mais que l'agent ne parvient pas à se lancer, Jenkins peut expirer lors de l'exécution des scripts d'initialisation. Augmentez le paramètre de délai d'attente de connexion SSH dans la page de configuration de l'agent.

5. Échecs courants de l'environnement de l'agent

Une fois la connexion réseau établie, l'agent peut encore échouer si son environnement d'exploitation est incorrect.

5.1 Environnement Java (Crucial)

L'agent Jenkins nécessite un environnement d'exécution Java (JRE/JDK) compatible pour exécuter le fichier agent.jar.

• Vérifier la présence de Java : Exécutez java -version sur la machine de l'agent.
• Vérifier JAVA_HOME : Assurez-vous que la variable JAVA_HOME ou Chemin vers JDK dans la configuration de l'agent Jenkins pointe vers un répertoire d'installation Java valide sur la machine de l'agent.

5.2 Espace de travail et permissions utilisateur

Le compte utilisateur que Jenkins utilise pour exécuter l'agent (soit via une connexion SSH, soit via un service système) doit avoir les permissions de lecture et d'écriture sur le répertoire racine distant défini (espace de travail).

• Action : Vérifiez la propriété et les permissions du répertoire racine distant (par exemple, /home/jenkins/workspace).

5.3 Synchronisation temporelle

Bien que rare, un décalage temporel important entre le contrôleur et la machine de l'agent peut provoquer des échecs de négociation SSL/TLS, entraînant des déconnexions ou des refus. Assurez-vous que les deux machines sont synchronisées via le protocole NTP (Network Time Protocol).

Conclusion et liste de contrôle

Le dépannage de la connectivité Jenkins est un processus d'élimination, en partant du périmètre réseau vers l'intérieur. En vérifiant systématiquement les pare-feux, en testant l'accessibilité des ports à l'aide d'outils comme telnet, et en confirmant que les protocoles de communication (JNLP ou SSH) sont correctement authentifiés et configurés, vous pouvez rapidement identifier et résoudre les problèmes de connectivité.

Liste de contrôle de dépannage :

1. Pare-feu réseau : Le trafic est-il autorisé dans les deux sens sur le port requis (50000+ pour JNLP, 22 pour SSH) ?
2. Pare-feu local : Le pare-feu du système d'exploitation (Windows/Linux) sur le contrôleur/agent bloque-t-il le port ?
3. Test de protocole : telnet réussit-il depuis la machine de connexion vers la destination sur le port concerné ?
4. Java : Une version Java compatible est-elle installée sur l'agent, et le chemin est-il correct ?
5. Authentification : Les clés/mots de passe SSH sont-ils valides, ou le jeton secret JNLP est-il à jour ?

Si toutes les tentatives de connexion échouent, vérifiez les journaux du contrôleur Jenkins, souvent disponibles dans le journal du service ou dans /var/log/jenkins/jenkins.log, pour les traces de remoting et les traces de pile Java.