Hub de Connaissances DevOps
Hub de Connaissances DevOps

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

Rétablissez votre environnement Jenkins en maîtrisant les étapes clés de dépannage de la connectivité. Ce guide se concentre sur le diagnostic et la résolution des problèmes liés à la communication Maître-Agent, couvrant les aspects réseau critiques tels que la configuration du pare-feu, les paramètres de port JNLP et les échecs d'authentification SSH. Apprenez à utiliser des outils comme `telnet` pour vérifier l'accessibilité et à comprendre les pièges environnementaux courants, garantissant que vos agents Jenkins restent en ligne et que vos pipelines CI/CD s'exécutent sans accroc.

36 vues

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

Jenkins repose fortement sur une communication robuste entre le contrôleur central (Master) 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'interrompt. Le diagnostic de ces problèmes nécessite une approche systématique, se concentrant souvent d'abord sur la topologie réseau, puis sur la configuration de l'agent et les échecs de protocole.

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

1. Comprendre la communication Master-Agent de Jenkins

Avant de dépanner, il est essentiel de comprendre comment le Master Jenkins (Contrôleur) communique avec ses Agents. Jenkins offre deux méthodes principales, chacune ayant des exigences de diagnostic uniques :

1.1 Protocole JNLP (Java Network Launch Protocol)

Dans le modèle JNLP, l'Agent Jenkins initie la connexion au Master. C'est l'approche recommandée et la plus courante. L'Agent se connecte à un port spécifique sur le Master (le port d'agent JNLP).

  • Direction : L'Agent se connecte AU Master.
  • Port requis : Le port JNLP du Master (souvent 50000 par défaut, ou attribué dynamiquement).

1.2 Secure Shell (SSH)

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

  • Direction : Le Master se connecte À l'Agent.
  • Port requis : Le port SSH de l'Agent (généralement 22).
  • Exigence : Les informations d'identification SSH (clés ou mots de passe) doivent être correctement configurées dans Jenkins.

2. Diagnostics initiaux du réseau et du pare-feu

Les problèmes de réseau, en particulier les restrictions du pare-feu, sont la cause la plus fréquente des problèmes de connectivité. Si un agent passe soudainement hors ligne ou si 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 du statut
Interface Web Utilisateur/Agent Master 8080 (ou personnalisé) Accès par navigateur
JNLP (Agent -> Master) Agent Master 50000 (ou personnalisé) telnet ou nc
SSH (Master -> Agent) Master Agent 22 (ou personnalisé) ssh ou telnet

2.2 Utilisation de Telnet/Netcat pour les tests de joignabilité

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

Vérification de la joignabilité JNLP (de l'Agent au Master)

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

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

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

Conseil : Une erreur "Connection Refused" (Connexion refusée) indique que le chemin réseau est ouvert, mais que le service (Jenkins) n'est pas à l'écoute sur ce port, ou qu'un pare-feu local sur le Master 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. Par défaut, Jenkins peut utiliser une plage de ports dynamique, ce qui complique les paramètres de sécurité.

  1. Naviguez vers Gérer Jenkins > Gérer les nœuds et les clouds > Configurer la sécurité globale.
  2. Sous Agents, trouvez l'option 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 Pare-feu Windows) sur la machine Master.

3. Dépannage des problèmes d'agent JNLP

Si les vérifications réseau sont réussies, le problème est généralement lié à l'authentification, à la configuration ou à une inadéquation de l'environnement.

3.1 Vérifier les journaux de l'agent sur le Master

Lors de la tentative de lancement d'un agent JNLP, consultez les journaux fournis par Jenkins lui-même. Naviguez vers 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 des erreurs courantes telles que java.net.ConnectException ou hudson.remoting.ChannelClosedException.

3.2 Assurer la correction des arguments de l'Agent

Lors du lancement manuel de l'agent à l'aide de la commande fournie par Jenkins (la commande java -jar agent.jar ...), assurez-vous que les paramètres sont corrects.

# Structure de commande exemple 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 du Master corrects. Si Jenkins se trouve derrière un proxy inverse, assurez-vous que la configuration du Master 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. Dépannage des problèmes d'agent SSH

Si vous utilisez SSH pour lancer des agents, les échecs de connexion proviennent généralement de 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 agent depuis le Master en utilisant le nom d'utilisateur et les informations d'identification 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é, les informations d'identification/clés de l'utilisateur sont incorrectes, 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'informations d'identification 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 (non recommandé 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 à démarrer, Jenkins peut dépasser le délai imparti lors de la tentative d'exécution des scripts d'initialisation. Augmentez le paramètre de délai d'attente de connexion SSH sur la page de configuration de l'Agent.

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

Même si la connexion réseau est établie, l'agent peut toujours é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 agent.
  • Vérifier JAVA_HOME : Assurez-vous que la variable JAVA_HOME ou Path to JDK dans la configuration de l'agent Jenkins pointe vers un répertoire d'installation Java valide sur la machine Agent.

5.2 Permissions de l'espace de travail et de l'utilisateur

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

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

5.3 Synchronisation de l'heure

Bien que peu fréquent, un décalage horaire important entre le Master et la machine Agent peut entraîner des échecs de poignée de main SSL/TLS, provoquant des déconnexions ou des refus de connexion. Assurez-vous que les deux machines sont synchronisées via le protocole NTP (Network Time Protocol).

Résumé et prochaines étapes

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

Liste de contrôle de dépannage :

  1. Pare-feu réseau : Le trafic est-il autorisé bidirectionnellement sur le port requis (50000+ pour JNLP, 22 pour SSH) ?
  2. Pare-feu local : Le pare-feu du système d'exploitation (Windows/Linux) en cours d'exécution sur le Master/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 pertinent ?
  4. Java : Une version compatible de Java 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 système (/var/log/jenkins/jenkins.log sur le Master) pour les traces de pile Java de bas niveau qui pourraient révéler des problèmes de configuration sous-jacents.