Risoluzione dei Problemi Comuni di Connettività degli Agenti Jenkins e Soluzioni

Gli agenti Jenkins, chiamati anche nodi, sono dove viene eseguita la maggior parte del lavoro di build. Quando uno va offline, il sintomo è ovvio: i job rimangono in coda, le etichette non possono essere soddisfatte e i team iniziano a rieseguire build che non sarebbero mai partite. Il lavoro utile è capire quale strato si è rotto: raggiungibilità di rete, SSH, remoting in entrata, Java, credenziali, disco o il controller stesso.

Capire perché un agente potrebbe diventare irraggiungibile è il primo passo per una risoluzione efficace dei problemi. Questi problemi possono derivare da configurazioni di rete errate, impostazioni errate dell'agente, restrizioni del firewall o problemi con il controller Jenkins stesso. Controllando sistematicamente queste aree, puoi identificare rapidamente la causa principale e implementare una soluzione.

Cause Comuni di Disconnessione dell'Agente Jenkins

Diversi fattori possono portare un agente a diventare offline. Identificare il sintomo specifico è fondamentale per restringere le potenziali cause:

Agente irraggiungibile: Il controller Jenkins non riesce a stabilire una connessione con l'agente.
Connessione rifiutata: La macchina agente rifiuta attivamente il tentativo di connessione dal controller.
Agente segnala offline dopo una connessione riuscita: L'agente era connesso ma ha successivamente perso la connessione.
Errori JSch (per agenti basati su SSH): Errori specifici relativi alla libreria Java Secure Channel utilizzata per le connessioni SSH.

Problemi di Rete e Firewall

La connettività di rete è la causa più frequente dei problemi di connessione degli agenti. Assicurarsi che il controller Jenkins possa raggiungere la macchina agente e viceversa è fondamentale.

Verifica della Raggiungibilità di Rete

Prima di addentrarci nelle configurazioni specifiche di Jenkins, conferma la connettività di rete di base:

Ping dell'agente: Dalla macchina del controller Jenkins, prova a eseguire il ping dell'indirizzo IP o del nome host della macchina agente.
```
ping <nome-host-o-ip-agente>
```
Telnet alla porta dell'agente: Verifica se la porta che Jenkins utilizza per connettersi all'agente è aperta e in ascolto. Per gli agenti JNLP, questa è tipicamente la porta 50000. Per gli agenti SSH, è la porta SSH (default 22).
```
telnet <nome-host-o-ip-agente> <porta-agente>
```
Se la connessione scade o viene rifiutata, probabilmente c'è un problema di rete o firewall che blocca la porta.

Configurazione del Firewall

I firewall sul controller Jenkins, sulla macchina agente o sui dispositivi di rete intermedi possono bloccare le porte necessarie.

Firewall del Controller Jenkins: Assicurati che il controller possa avviare connessioni alla porta dell'agente.
Firewall della Macchina Agente: Assicurati che il firewall della macchina agente (es. ufw, firewalld, Windows Firewall) permetta connessioni in entrata sulla porta dell'agente dall'indirizzo IP del controller Jenkins.
Firewall di Rete: Se la tua rete ha firewall interni, verifica che il traffico sia consentito tra il controller e l'agente.

Esempio: Consentire la Porta 50000 su un Agente (Linux con `ufw`)

# Consenti connessioni da un IP specifico (controller Jenkins)
sudo ufw allow from <ip-controller-jenkins> to any port 50000

# Oppure consenti da qualsiasi IP (meno sicuro)
sudo ufw allow 50000

# Ricarica le regole del firewall
sudo ufw reload

Esempio: Consentire la Porta 22 su un Agente (Linux con `firewalld`)

# Consenti il servizio SSH permanentemente da un IP sorgente specifico
sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="<ip-controller-jenkins>" port protocol="tcp" port="22" accept'

# Ricarica le regole del firewall
sudo firewall-cmd --reload

Suggerimento: Dai sempre la priorità al consentire connessioni da indirizzi IP specifici per una maggiore sicurezza.

Problemi di Configurazione dell'Agente Jenkins

Configurazioni errate all'interno di Jenkins o sull'agente stesso sono fonti comuni di problemi di connettività.

Configurazione dell'Agente JNLP

Gli agenti Java Network Launch Protocol (JNLP) comunicano con il controller Jenkins utilizzando una porta dedicata. La configurazione principale riguarda il metodo di avvio dell'agente e le porte disponibili del controller.

Agente Offline nell'Interfaccia Utente di Jenkins

Se un agente appare offline nell'interfaccia utente di Jenkins, significa che il controller non è riuscito a stabilire o mantenere una connessione.

Controlla il Metodo di Avvio dell'Agente: Assicurati che l'agente sia configurato per avviarsi correttamente. I metodi comuni includono:
- Avvia agente collegandolo al master: Richiede l'inizializzazione manuale dal lato agente.
- Avvia agente tramite SSH: Configurato tramite credenziali SSH e impostazioni host.
- Avvia agente utilizzando proprietà del nodo integrate: Per scenari specifici.
Verifica la Disponibilità della Porta JNLP: Il controller Jenkins deve essere in ascolto sulla porta JNLP configurata (default 50000). Vai su Gestisci Jenkins -> Sistema -> Avanzate -> File -> Porta TCP per agenti JNLP e assicurati che sia impostata e accessibile.

"Connessione rifiutata" durante l'avvio dell'Agente JNLP

Questo spesso significa che la porta JNLP (default 50000) sul controller Jenkins non è aperta o accessibile dalla macchina agente. Verifica le regole del firewall sul controller e assicurati che la porta sia configurata correttamente.

Suggerimento: Riavviare il controller Jenkins può talvolta risolvere problemi transitori della porta JNLP.

Configurazione dell'Agente SSH

Quando si utilizza SSH per connettersi agli agenti, diversi fattori possono causare problemi:

Credenziali SSH Errate: Verifica il nome utente, la password o la chiave privata configurati in Jenkins per la connessione SSH. Assicurati che la chiave privata sia formattata correttamente (es. formato PEM) e abbia i permessi corretti.
Server SSH Non in Esecuzione sull'Agente: Assicurati che il demone SSH (sshd) sia in esecuzione sulla macchina agente.
```
# Sulla macchina agente
sudo systemctl status sshd
# oppure
sudo service ssh status
```
Se non è in esecuzione, avvialo:
```
sudo systemctl start sshd
sudo systemctl enable sshd
```
Mancata Corrispondenza della Porta SSH: Assicurati che la porta configurata in Jenkins per SSH corrisponda alla porta su cui il server SSH è in ascolto (default 22).
Risoluzione Nome Host/IP dell'Agente: Il controller Jenkins deve essere in grado di risolvere il nome host o l'indirizzo IP dell'agente.
Permessi della Chiave SSH: Sulla macchina agente, il file ~/.ssh/authorized_keys per l'utente con cui Jenkins si connette deve avere i permessi corretti (di solito 600).

Esempio: Test Manuale della Connessione SSH

Dalla macchina del controller Jenkins, prova a connetterti via SSH all'agente utilizzando le stesse credenziali e porta configurate in Jenkins:

ssh -p <porta-ssh> <utente-jenkins>@<nome-host-o-ip-agente>

Se questo comando SSH manuale fallisce, il problema è al di fuori della configurazione SSH di Jenkins, probabilmente nelle impostazioni di rete, firewall o server SSH sull'agente.

Permessi della Directory di Lavoro dell'Agente

Jenkins richiede permessi specifici per operare sul filesystem dell'agente. L'utente che Jenkins utilizza per connettersi all'agente (o l'utente che esegue il processo agente) necessita di permessi di scrittura sulla directory di lavoro configurata dell'agente.

Verifica proprietario e permessi: Sull'agente, controlla la proprietà e i permessi della home directory di Jenkins e delle sue sottodirectory.
```
ls -ld /percorso/della/home/agente/jenkins
ls -l /percorso/della/home/agente/jenkins
```
Concedi permessi (se necessario): Assicurati che l'utente con cui Jenkins si connette abbia accesso in lettura e scrittura. Usa chown e chmod con cautela.

Problemi del Controller Jenkins

A volte, il problema potrebbe non essere con l'agente ma con il controller Jenkins stesso.

Sovraccarico del Controller

Se il controller Jenkins è sotto carico pesante (molti job in esecuzione, uso elevato di CPU/memoria), potrebbe avere difficoltà a gestire le connessioni degli agenti. Monitora l'utilizzo delle risorse del controller.

Conflitti di Porta JNLP

Se la porta JNLP (default 50000) è già in uso da un altro processo sul controller Jenkins, gli agenti non riusciranno a connettersi.

Controlla l'uso della porta: Sulla macchina del controller, usa netstat o ss per vedere quale processo sta usando la porta.
```
sudo netstat -tulnp | grep 50000
# oppure
sudo ss -tulnp | grep 50000
```
Se un altro processo la sta usando, dovrai riconfigurare Jenkins o l'altra applicazione per utilizzare porte diverse.

Risoluzione Avanzata dei Problemi e Log

Quando i controlli standard non rivelano il problema, è necessaria un'indagine più approfondita.

Log del Controller Jenkins

Esamina i log del controller Jenkins per errori relativi alle connessioni degli agenti. Questi log possono fornire messaggi di errore specifici.

Posizione: Tipicamente si trovano in $JENKINS_HOME/jenkins.log o accessibili tramite Gestisci Jenkins -> Log di Sistema.
Cerca: Messaggi che menzionano il nome host dell'agente, l'indirizzo IP, i tentativi di connessione, eccezioni JSch o errori di "Connessione rifiutata".

Log dell'Agente

Se l'agente è in esecuzione ma segnala offline, controlla i suoi log per eventuali errori.

Agenti JNLP: Il processo agente stesso potrebbe produrre log sulla sua console o in un file di log designato.
Agenti SSH: I log potrebbero essere in $JENKINS_HOME/agent.log sulla macchina agente, o relativi a sshd se la connessione fallisce a livello SSH.

Abilita il Debug Logging

Per problemi molto persistenti, abilitare temporaneamente il debug logging per i componenti Jenkins pertinenti può fornire informazioni più granulari.

Comunicazione JNLP/Agente: Potrebbe essere necessario regolare le proprietà di sistema Java o utilizzare la configurazione di logging di Jenkins (Gestisci Jenkins -> Log di Sistema -> Registratori di Log) per aumentare la verbosità per hudson.slaves o pacchetti correlati.

Abitudini Pratiche che Prevengono Interruzioni Ricorrenti

La risoluzione dei problemi di connettività degli agenti Jenkins richiede un approccio sistematico, iniziando con i controlli di rete di base e procedendo verso le configurazioni specifiche di Jenkins.

Verifica la Rete: Inizia sempre con ping e telnet/nc per assicurarti della raggiungibilità di rete di base e dell'accesso alla porta.
Controlla i Firewall: Assicurati che i firewall sia sul controller che sull'agente, così come eventuali firewall di rete, permettano il traffico sulle porte richieste.
Convalida le Credenziali: Ricontrolla chiavi SSH, nomi utente e password.
Conferma il Servizio Agente: Per gli agenti SSH, assicurati che sshd sia in esecuzione e accessibile.
Monitora i Log di Jenkins: I log del controller sono la tua fonte principale per comprendere i fallimenti di connessione.
Usa IP Specifici: Dove possibile, configura i firewall e Jenkins per utilizzare indirizzi IP specifici piuttosto che intervalli ampi o 0.0.0.0.

Seguendo questi passaggi, puoi diagnosticare e risolvere efficacemente la maggior parte dei problemi comuni di connettività degli agenti Jenkins, mantenendo le tue pipeline CI/CD funzionanti senza intoppi.

Leggere il Messaggio di Offline Senza Indovinare

La parola "offline" è troppo generica per risolvere i problemi da sola. Prima di modificare le impostazioni di Jenkins, apri la pagina dell'agente e leggi il motivo esatto fornito da Jenkins. C'è una grande differenza tra "connessione rifiutata", "permesso negato", "verifica della chiave host fallita", "agente JNLP rifiutato" e "canale chiuso". Tutti terminano con un nodo offline, ma puntano a strati diversi.

Di solito scrivo il sintomo in linguaggio semplice: "il controller non può raggiungere la porta TCP 22", "il login SSH funziona ma Java non può avviarsi", "l'agente in entrata si avvia ma non può richiamare il controller", o "l'agente si connette e poi cade durante le build". Quella singola frase mantiene l'indagine focalizzata.

Se l'agente non si è mai connesso, sospetta configurazione, DNS, firewall, credenziali o comando di avvio. Se si è connesso per mesi e ha iniziato a fallire oggi, controlla i cambiamenti recenti: chiavi SSH ruotate, un aggiornamento di Jenkins, un aggiornamento di un plugin, una nuova regola del firewall, un certificato scaduto, una ricostruzione dell'immagine dell'agente o una modifica della rete cloud. La cronologia è spesso più utile del testo dell'errore.

Agenti SSH: Separa i Problemi di Login dai Problemi di Avvio

Per gli agenti basati su SSH, testa lo stesso percorso utilizzato da Jenkins. Dall'host del controller, connettiti come utente configurato in Jenkins:

ssh -vvv utente-agente-jenkins@nome-host-agente

L'output verboso ti dice se il fallimento avviene prima dell'autenticazione, durante l'autenticazione o dopo il login. Se SSH non raggiunge mai il server, Jenkins non può risolvere il problema. Controlla routing, gruppi di sicurezza, ACL di rete, firewall host e il demone SSH. Se SSH raggiunge il server ma rifiuta la chiave, controlla la credenziale in Jenkins, le authorized_keys dell'utente, i permessi dei file e se l'account è bloccato.

Se il login SSH funziona manualmente ma Jenkins fallisce ancora, guarda la directory remota root e l'avvio di Java. Jenkins ha bisogno di una directory scrivibile per i file di remoting, e l'utente agente necessita del permesso per creare file lì. Un errore comune è puntare la root remota a un percorso di proprietà di root o pulito da un altro processo.

Esegui questi controlli sull'agente:

whoami
pwd
java -version
test -w /percorso/dell/agente/jenkins && echo scrivibile
df -h /percorso/dell/agente/jenkins

La versione di Java è importante perché i controller Jenkins moderni richiedono versioni Java compatibili sugli agenti. Il requisito esatto dipende dalla tua versione di Jenkins, quindi controlla la documentazione di Jenkins per la tua versione invece di presumere che una vecchia immagine agente sia ancora valida.

Agenti Inbound: Il Percorso di Callback è la Trappola Comune

Gli agenti inbound sono spesso utilizzati quando il controller non può avviare SSH verso l'agente, come agenti dietro NAT o in reti ristrette. Il processo agente si avvia al di fuori di Jenkins e si riconnette al controller. Ciò significa che il percorso di rete è invertito: l'agente deve risolvere e raggiungere l'URL di Jenkins.

Sull'host agente, testa l'URL di Jenkins esattamente come configurato:

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

Se Jenkins è dietro un proxy inverso, conferma che l'URL pubblico in Gestisci Jenkins > Sistema sia corretto. Un URL Jenkins sbagliato può far sì che i comandi generati per l'agente puntino a un nome host interno che l'agente non può risolvere. Se la modalità WebSocket è abilitata per gli agenti inbound, assicurati che il proxy supporti gli header di upgrade WebSocket. Se usi invece la porta TCP per agenti inbound, conferma che la porta fissa sia configurata e raggiungibile dalla rete dell'agente.

I problemi TLS possono sembrare problemi di Jenkins. Se l'agente viene eseguito in un'immagine contenitore minimale, potrebbe non avere il certificato CA interno. curl di solito lo rivelerà rapidamente. Installa il certificato CA nell'immagine agente invece di disabilitare la verifica del certificato.

Agenti che si Disconnettono Durante le Build

Un agente che si connette con successo e poi cade durante una build di solito non è un problema di connettività di base. Controlla la pressione sulle risorse e il ciclo di vita del processo.

Verifica se il sistema operativo ha ucciso il processo agente:

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

Controlla anche lo spazio su disco. Il remoting di Jenkins, il checkout, i report di test e gli artefatti archiviati necessitano tutti di spazio. Un volume del workspace pieno può far sembrare un agente inaffidabile perché il processo di remoting non può scrivere file temporanei o log.

Se le disconnessioni avvengono durante output di console grandi, archiviazione di artefatti o pubblicazione di report di test, guarda la stabilità della rete e il carico del controller. Il canale agente è una connessione live. Lunghe pause di garbage collection sul controller, proxy sovraccarichi, timeout di connessione inattivi e perdita di pacchetti possono tutti chiuderlo. Per agenti che attraversano bilanciatori di carico o proxy aziendali, verifica le impostazioni di timeout di inattività e il comportamento di keepalive.

Problemi di DNS e Chiave Host

I cambiamenti DNS sono facili da trascurare. Jenkins potrebbe connettersi a build-agent-01, mentre il tuo test manuale utilizza un indirizzo IP. Testa il nome host dal controller:

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

Se il nome host si risolve nell'indirizzo sbagliato, correggi il DNS o la configurazione dell'agente. Evita patch a lungo termine in /etc/hosts a meno che tu non abbia un chiaro processo di proprietà, perché diventano infrastruttura invisibile.

Per gli agenti SSH, la verifica della chiave host protegge Jenkins dal connettersi a una macchina imprevista. Se un agente è stato ricostruito, la sua chiave host potrebbe essere cambiata. Non disabilitare ciecamente la verifica. Conferma la ricostruzione, rimuovi la vecchia chiave dal known_hosts dell'utente del controller e accetta la nuova chiave attraverso la strategia Jenkins configurata.

Una Checklist di Recupero per Agenti di Produzione

Quando diversi agenti vanno offline contemporaneamente, evita di ripararli uno per uno prima di trovare la causa comune. Chiedi:

Il controller Jenkins è stato riavviato o aggiornato?
Una credenziale condivisa è stata ruotata?
Un'immagine base dell'agente è cambiata?
Un firewall, proxy, VPN o DNS è stato modificato?
Tutti gli agenti falliti sono nella stessa subnet, account cloud, namespace Kubernetes o zona di disponibilità?

Se solo un agente fallisce, ispeziona quell'host. Se un intero gruppo fallisce insieme, ispeziona la dipendenza comune. Questo fa risparmiare molto tempo in flotte Jenkins più grandi.