Centro di Conoscenza DevOps
Centro di Conoscenza DevOps

Diagnosi dei problemi di connettività di Jenkins: problemi di rete e agenti

Ripristina il tuo ambiente Jenkins padroneggiando i passaggi chiave per la risoluzione dei problemi di connettività. Questa guida si concentra sulla diagnosi e sulla risoluzione dei problemi relativi alla comunicazione Master-Agente, coprendo aspetti di rete critici come la configurazione del firewall, le impostazioni delle porte JNLP e i guasti all'autenticazione SSH. Scopri come utilizzare strumenti come `telnet` per verificare la raggiungibilità e comprendere le insidie ambientali comuni, assicurando che i tuoi agenti Jenkins rimangano online e che le tue pipeline CI/CD funzionino senza problemi.

41 visualizzazioni

Diagnostica dei Problemi di Connettività Jenkins: Problemi di Rete e Agente

Jenkins si basa fortemente su una comunicazione robusta tra il controller centrale (Master) e i suoi ambienti di esecuzione (Agenti o Nodi). Quando questa connettività fallisce, le build si bloccano, le pipeline si fermano e l'integrazione continua si arresta. La diagnosi di questi problemi richiede un approccio sistematico, spesso concentrandosi prima sulla topologia di rete, poi sulla configurazione dell'agente e sui fallimenti del protocollo.

Questa guida completa fornisce istruzioni passo-passo per risolvere i problemi di connettività Jenkins più comuni, inclusi problemi elusivi del firewall, porte JNLP mal configurate e fallimenti all'avvio dell'agente, aiutandovi a ripristinare rapidamente operazioni stabili e pipeline CI/CD affidabili.

1. Comprendere la Comunicazione Master-Agent di Jenkins

Prima della risoluzione dei problemi, è essenziale comprendere come il Master Jenkins (Controller) comunica con i suoi Agenti. Jenkins offre due metodi principali, ciascuno con requisiti diagnostici unici:

1.1 Java Network Launch Protocol (JNLP)

Nel modello JNLP, l'Agente Jenkins avvia la connessione al Master. Questo è l'approccio raccomandato e più comune. L'Agente si connette a una porta specifica sul Master (la Porta Agente JNLP).

  • Direzione: L'Agente si connette AL Master.
  • Porta Richiesta: La porta JNLP del Master (spesso 50000 per impostazione predefinita, o assegnata dinamicamente).

1.2 Secure Shell (SSH)

Nel modello SSH, il Master Jenkins avvia la connessione all'Agente. Questo richiede che la macchina Agente esegua un server SSH.

  • Direzione: Il Master si connette ALL'Agente.
  • Porta Richiesta: La porta SSH dell'Agente (tipicamente 22).
  • Requisito: Le credenziali SSH (chiavi o password) devono essere configurate correttamente in Jenkins.

2. Diagnostica Iniziale di Rete e Firewall

I problemi di rete, in particolare le restrizioni del firewall, sono la causa più frequente di problemi di connettività. Se un agente si disconnette improvvisamente o un nuovo agente non riesce a connettersi, iniziare da qui.

2.1 Verificare che le Porte Richieste Siano Aperte

È necessario assicurarsi che il traffico possa fluire sulle porte necessarie in base al proprio modello di comunicazione.

Tipo di Connessione Sorgente Destinazione Porta Richiesta Controllo Stato
Interfaccia Web Utente/Agente Master 8080 (o personalizzata) Accesso tramite browser
JNLP (Agente -> Master) Agente Master 50000 (o personalizzata) telnet o nc
SSH (Master -> Agente) Master Agente 22 (o personalizzata) ssh o telnet

2.2 Utilizzo di Telnet/Netcat per Test di Raggiungibilità

Utilizzare telnet o nc (Netcat) dalla macchina che si connette alla macchina di destinazione sulla porta richiesta. Una connessione riuscita conferma la raggiungibilità della rete e che nessun firewall locale sta bloccando la porta.

Controllo Raggiungibilità JNLP (dall'Agente al Master)

# Sostituire <MASTER_IP> e <JNLP_PORT>
telnet <MASTER_IP> 50000

# Output previsto in caso di successo:
# Connected to <MASTER_IP>.
# Escape character is '^]'.

# Output previsto in caso di fallimento:
# Trying <MASTER_IP>...
# telnet: connect to address <MASTER_IP>: Connection refused

Suggerimento: Un errore "Connection Refused" (Connessione rifiutata) indica che il percorso di rete è aperto, ma il servizio (Jenkins) non è in ascolto su quella porta, oppure un firewall locale sul Master lo sta bloccando. Se la connessione va in timeout, è probabile che un firewall tra le macchine sia il colpevole.

2.3 Impostare una Porta JNLP Fissa

Se si utilizza JNLP, è buona pratica configurare una porta fissa per evitare ambiguità e semplificare le regole del firewall. Per impostazione predefinita, Jenkins potrebbe utilizzare un intervallo di porte dinamico, il che complica le impostazioni di sicurezza.

  1. Andare su Gestisci Jenkins > Gestisci Nodi e Cloud > Configura Sicurezza Globale.
  2. Sotto Agenti, trovare l'opzione per Porta TCP per agenti in ingresso.
  3. Selezionare Fissa e specificare una porta (es. 50000).
  4. Assicurarsi che questa porta sia aperta nel firewall del sistema operativo host (es. iptables, firewalld o Windows Firewall) sulla macchina Master.

3. Risoluzione dei Problemi dell'Agente JNLP

Se i controlli di rete hanno successo, il problema è tipicamente correlato all'autenticazione, alla configurazione o a una non corrispondenza dell'ambiente.

3.1 Controllare i Log dell'Agente sul Master

Quando si tenta di avviare un agente JNLP, esaminare i log forniti da Jenkins stesso. Navigare alla pagina di configurazione specifica dell'Agente e visualizzare la sezione Log. Questo spesso fornisce il messaggio di errore più chiaro.

  • Cercare errori comuni come java.net.ConnectException o hudson.remoting.ChannelClosedException.

3.2 Assicurarsi che gli Argomenti dell'Agente Siano Corretti

Quando si avvia l'agente manualmente utilizzando il comando fornito da Jenkins (il comando java -jar agent.jar ...), assicurarsi che i parametri siano corretti.

# Esempio di struttura del comando per l'avvio JNLP
java -jar agent.jar -jnlpUrl http://<JENKINS_URL>/computer/<AGENT_NAME>/slave-agent.jnlp -secret <SECRET_TOKEN> -workDir "/path/to/workspace"
  • Verificare l'URL JNLP: Assicurarsi che l'URL utilizzi il nome host e la porta corretti del Master. Se Jenkins è dietro un reverse proxy, assicurarsi che la configurazione del Master rifletta l'URL esterno.
  • Verificare il Token Segreto: I token scadono o cambiano se il nodo viene riconfigurato. Scaricare il .jar più recente e utilizzare l'ultimo segreto fornito nella pagina di avvio dell'Agente.

4. Risoluzione dei Problemi dell'Agente SSH

Se si utilizza SSH per avviare gli agenti, i fallimenti di connettività sono solitamente radicati in problemi di autenticazione o di ambiente shell.

4.1 Verificare la Connessione SSH Esternamente a Jenkins

Tentare di connettersi alla macchina agente dal Master utilizzando l'esatto nome utente e le credenziali configurate in Jenkins.

ssh -i /path/to/keyfile jenkins_user@<AGENT_IP>
  • Se ciò fallisce, il problema è ambientale: il servizio SSH è inattivo, le credenziali/chiavi utente sono errate, o i permessi della chiave sono troppo permissivi (chmod 600 keyfile.pem).

4.2 Controllare il Metodo di Autenticazione SSH

  1. Chiavi: Assicurarsi che la chiave pubblica corrispondente alla chiave privata memorizzata in Jenkins Credentials Manager sia correttamente aggiunta al file ~/.ssh/authorized_keys dell'utente dell'agente.
  2. Password: Se si utilizzano le password, assicurarsi che il server SSH sull'agente sia configurato per consentire l'autenticazione tramite password (non raccomandato per motivi di sicurezza).

4.3 Timeout di Avvio dell'Agente SSH

Se la connessione SSH ha successo ma l'agente non riesce ad avviarsi, Jenkins potrebbe andare in timeout mentre tenta di eseguire gli script di inizializzazione. Aumentare l'impostazione del timeout di connessione SSH nella pagina di configurazione dell'Agente.

5. Errori Comuni nell'Ambiente dell'Agente

Una volta stabilita la connessione di rete, l'agente potrebbe comunque fallire se il suo ambiente operativo è errato.

5.1 Ambiente Java (Cruciale)

L'agente Jenkins richiede un Java Runtime Environment (JRE/JDK) compatibile per eseguire il file agent.jar.

  • Verificare la Presenza di Java: Eseguire java -version sulla macchina agente.
  • Verificare JAVA_HOME: Assicurarsi che la variabile JAVA_HOME o Path to JDK nella configurazione dell'agente Jenkins punti a una directory di installazione Java valida sulla macchina Agente.

5.2 Permessi di Workspace e Utente

L'account utente che Jenkins utilizza per eseguire l'agente (sia tramite login SSH che servizio di sistema) deve avere permessi di lettura e scrittura sulla directory root remota definita (workspace).

  • Azione: Verificare la proprietà e i permessi della directory root remota (es. /home/jenkins/workspace).

5.3 Sincronizzazione dell'Ora

Sebbene non comune, una deriva temporale significativa tra il Master e la macchina Agente può causare fallimenti nell'handshake SSL/TLS, con conseguenti interruzioni o rifiuti di connessione. Assicurarsi che entrambe le macchine siano sincronizzate tramite Network Time Protocol (NTP).

Riepilogo e Passi Successivi

La risoluzione dei problemi di connettività di Jenkins è un processo di eliminazione, che inizia dal perimetro della rete verso l'interno. Controllando sistematicamente i firewall, verificando la raggiungibilità delle porte utilizzando strumenti come telnet e confermando che i protocolli di comunicazione (JNLP o SSH) siano correttamente autenticati e configurati, è possibile individuare e risolvere rapidamente i problemi di connettività.

Lista di Controllo per la Risoluzione dei Problemi:

  1. Firewall di Rete: Il traffico è consentito bidirezionalmente sulla porta richiesta (50000+ per JNLP, 22 per SSH)?
  2. Firewall Locale: Il firewall del sistema operativo (Windows/Linux) in esecuzione sul Master/Agente sta bloccando la porta?
  3. Test del Protocollo: telnet ha successo dalla macchina che si connette alla destinazione sulla porta pertinente?
  4. Java: È installata una versione Java compatibile sull'Agente, e il percorso è corretto?
  5. Autenticazione: Le chiavi/password SSH sono valide, o il token segreto JNLP è attuale?

Se tutti i tentativi di connessione falliscono, controllare i log di sistema (/var/log/jenkins/jenkins.log sul Master) per stack trace Java di livello profondo che potrebbero rivelare problemi di configurazione sottostanti.