Fehlerbehebung bei häufigen Jenkins-Agent-Konnektivitätsproblemen und Lösungen

Jenkins-Agents, auch Nodes genannt, sind die Umgebungen, in denen die meiste Build-Arbeit tatsächlich ausgeführt wird. Wenn ein Agent offline geht, ist das Symptom offensichtlich: Jobs bleiben in der Warteschlange, Labels können nicht bedient werden, und Teams starten Builds neu, die ohnehin nie gestartet wären. Die nützliche Arbeit besteht darin, herauszufinden, welche Schicht ausgefallen ist: Netzwerkerreichbarkeit, SSH, Inbound-Remoting, Java, Anmeldeinformationen, Festplatte oder der Controller selbst.

Zu verstehen, warum ein Agent möglicherweise nicht erreichbar ist, ist der erste Schritt zur effektiven Fehlerbehebung. Diese Probleme können auf Netzwerkfehlkonfigurationen, falsche Agent-Einrichtung, Firewall-Einschränkungen oder Probleme mit dem Jenkins-Controller selbst zurückzuführen sein. Durch systematisches Überprüfen dieser Bereiche können Sie schnell die Ursache identifizieren und eine Lösung implementieren.

Häufige Ursachen für die Trennung von Jenkins-Agents

Mehrere Faktoren können dazu führen, dass ein Agent offline geht. Die Identifizierung des spezifischen Symptoms ist der Schlüssel zur Eingrenzung der möglichen Ursachen:

Agent nicht erreichbar: Der Jenkins-Controller kann keine Verbindung zum Agenten herstellen.
Verbindung abgelehnt: Der Agent-Rechner lehnt den Verbindungsversuch des Controllers aktiv ab.
Agent meldet nach erfolgreicher Verbindung offline: Der Agent war verbunden, hat die Verbindung aber abgebrochen.
JSch-Fehler (für SSH-basierte Agents): Spezifische Fehler im Zusammenhang mit der Java Secure Channel-Bibliothek, die für SSH-Verbindungen verwendet wird.

Netzwerk- und Firewall-Probleme

Die Netzwerkkonnektivität ist der häufigste Übeltäter bei Agent-Verbindungsproblemen. Es ist von größter Bedeutung, sicherzustellen, dass der Jenkins-Controller den Agent-Rechner erreichen kann und umgekehrt.

Überprüfen der Netzwerkerreichbarkeit

Bevor Sie sich mit Jenkins-spezifischen Konfigurationen befassen, bestätigen Sie die grundlegende Netzwerkkonnektivität:

Pingen Sie den Agenten: Versuchen Sie vom Jenkins-Controller-Rechner aus, die IP-Adresse oder den Hostnamen des Agent-Rechners anzupingen.
```
ping <agent-hostname-or-ip>
```
Telnet zum Agent-Port: Testen Sie, ob der Port, den Jenkins zum Verbinden mit dem Agenten verwendet, offen ist und lauscht. Für JNLP-Agents ist dies typischerweise Port 50000. Für SSH-Agents ist es der SSH-Port (Standard 22).
```
telnet <agent-hostname-or-ip> <agent-port>
```
Wenn die Verbindung zeitüberschreitet oder abgelehnt wird, liegt wahrscheinlich ein Netzwerk- oder Firewall-Problem vor, das den Port blockiert.

Firewall-Konfiguration

Firewalls auf dem Jenkins-Controller, dem Agent-Rechner oder zwischengeschalteten Netzwerkgeräten können die erforderlichen Ports blockieren.

Jenkins-Controller-Firewall: Stellen Sie sicher, dass der Controller Verbindungen zum Agent-Port initiieren kann.
Firewall des Agent-Rechners: Stellen Sie sicher, dass die Firewall des Agent-Rechners (z. B. ufw, firewalld, Windows-Firewall) eingehende Verbindungen zum Agent-Port von der IP-Adresse des Jenkins-Controllers zulässt.
Netzwerk-Firewalls: Wenn Ihr Netzwerk interne Firewalls hat, überprüfen Sie, ob der Datenverkehr zwischen Controller und Agent erlaubt ist.

Beispiel: Freigabe von Port 50000 auf einem Agenten (Linux mit `ufw`)

# Verbindungen von einer bestimmten IP (Jenkins-Controller) zulassen
sudo ufw allow from <jenkins-controller-ip> to any port 50000

# Oder von jeder IP zulassen (weniger sicher)
sudo ufw allow 50000

# Firewall-Regeln neu laden
sudo ufw reload

Beispiel: Freigabe von Port 22 auf einem Agenten (Linux mit `firewalld`)

# SSH-Dienst dauerhaft von einer bestimmten Quell-IP zulassen
sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="<jenkins-controller-ip>" port protocol="tcp" port="22" accept'

# Firewall-Regeln neu laden
sudo firewall-cmd --reload

Tipp: Priorisieren Sie aus Sicherheitsgründen immer das Zulassen von Verbindungen von bestimmten IP-Adressen.

Probleme mit der Jenkins-Agent-Konfiguration

Fehlkonfigurationen innerhalb von Jenkins oder auf dem Agenten selbst sind häufige Quellen für Konnektivitätsprobleme.

JNLP-Agent-Konfiguration

JNLP-Agents (Java Network Launch Protocol) kommunizieren mit dem Jenkins-Controller über einen dedizierten Port. Die primäre Konfiguration betrifft die Startmethode des Agents und die verfügbaren Ports des Controllers.

Agent ist in der Jenkins-Benutzeroberfläche offline

Wenn ein Agent in der Jenkins-Benutzeroberfläche als offline angezeigt wird, bedeutet dies, dass der Controller keine Verbindung herstellen oder aufrechterhalten konnte.

Überprüfen Sie die Agent-Startmethode: Stellen Sie sicher, dass der Agent korrekt gestartet wird. Übliche Methoden sind:
- Agent starten, indem Sie ihn mit dem Master verbinden: Dies erfordert eine manuelle Initiierung von der Agent-Seite.
- Agent per SSH starten: Konfiguriert über SSH-Anmeldeinformationen und Host-Einstellungen.
- Agent mit integrierten Node-Eigenschaften starten: Für bestimmte Szenarien.
Überprüfen Sie die Verfügbarkeit des JNLP-Ports: Der Jenkins-Controller muss auf dem konfigurierten JNLP-Port (Standard 50000) lauschen. Navigieren Sie zu Jenkins verwalten -> System -> Erweitert -> Datei -> TCP-Port für JNLP-Agents und stellen Sie sicher, dass er gesetzt und zugänglich ist.

"Verbindung abgelehnt" beim Starten des JNLP-Agents

Dies bedeutet oft, dass der JNLP-Port (Standard 50000) auf dem Jenkins-Controller nicht geöffnet oder vom Agent-Rechner aus nicht erreichbar ist. Überprüfen Sie die Firewall-Regeln auf dem Controller und stellen Sie sicher, dass der Port korrekt konfiguriert ist.

Tipp: Ein Neustart des Jenkins-Controllers kann manchmal vorübergehende JNLP-Port-Probleme beheben.

SSH-Agent-Konfiguration

Bei Verwendung von SSH zur Verbindung mit Agents können mehrere Faktoren Probleme verursachen:

Falsche SSH-Anmeldeinformationen: Überprüfen Sie den Benutzernamen, das Passwort oder den privaten Schlüssel, der in Jenkins für die SSH-Verbindung konfiguriert ist. Stellen Sie sicher, dass der private Schlüssel korrekt formatiert ist (z. B. PEM-Format) und die richtigen Berechtigungen hat.
SSH-Server läuft nicht auf dem Agenten: Stellen Sie sicher, dass der SSH-Daemon (sshd) auf dem Agent-Rechner läuft.
```
# Auf dem Agent-Rechner
sudo systemctl status sshd
# oder
sudo service ssh status
```
Wenn er nicht läuft, starten Sie ihn:
```
sudo systemctl start sshd
sudo systemctl enable sshd
```
SSH-Port stimmt nicht überein: Stellen Sie sicher, dass der in Jenkins für SSH konfigurierte Port mit dem Port übereinstimmt, auf dem der SSH-Server lauscht (Standard 22).
Agent-Hostname/IP-Auflösung: Der Jenkins-Controller muss in der Lage sein, den Hostnamen oder die IP-Adresse des Agents aufzulösen.
SSH-Schlüsselberechtigungen: Auf dem Agent-Rechner muss die Datei ~/.ssh/authorized_keys für den Benutzer, mit dem Jenkins eine Verbindung herstellt, die korrekten Berechtigungen haben (normalerweise 600).

Beispiel: Manuelles Testen der SSH-Verbindung

Versuchen Sie vom Jenkins-Controller-Rechner aus, mit denselben Anmeldeinformationen und demselben Port, die in Jenkins konfiguriert sind, eine SSH-Verbindung zum Agenten herzustellen:

ssh -p <ssh-port> <jenkins-user>@<agent-hostname-or-ip>

Wenn dieser manuelle SSH-Befehl fehlschlägt, liegt das Problem außerhalb der Jenkins-SSH-Konfiguration, wahrscheinlich in den Netzwerk-, Firewall- oder SSH-Server-Einstellungen auf dem Agenten.

Berechtigungen für das Agent-Arbeitsverzeichnis

Jenkins benötigt bestimmte Berechtigungen, um im Dateisystem des Agents zu arbeiten. Der Benutzer, den Jenkins zum Verbinden mit dem Agenten verwendet (oder der Benutzer, der den Agent-Prozess ausführt), benötigt Schreibberechtigungen für das konfigurierte Arbeitsverzeichnis des Agents.

Besitzer und Berechtigungen überprüfen: Überprüfen Sie auf dem Agenten den Besitzer und die Berechtigungen des Jenkins-Home-Verzeichnisses und seiner Unterverzeichnisse.
```
ls -ld /path/to/jenkins/agent/home
ls -l /path/to/jenkins/agent/home
```
Berechtigungen erteilen (falls erforderlich): Stellen Sie sicher, dass der Benutzer, mit dem Jenkins eine Verbindung herstellt, Lese- und Schreibzugriff hat. Verwenden Sie chown und chmod mit Vorsicht.

Probleme mit dem Jenkins-Controller

Manchmal liegt das Problem möglicherweise nicht am Agenten, sondern am Jenkins-Controller selbst.

Controller-Überlastung

Wenn der Jenkins-Controller stark ausgelastet ist (viele laufende Jobs, hohe CPU-/Speicherauslastung), könnte er Schwierigkeiten haben, Agent-Verbindungen zu verwalten. Überwachen Sie die Ressourcennutzung des Controllers.

JNLP-Port-Konflikte

Wenn der JNLP-Port (Standard 50000) bereits von einem anderen Prozess auf dem Jenkins-Controller verwendet wird, können Agents keine Verbindung herstellen.

Portnutzung überprüfen: Verwenden Sie auf dem Controller-Rechner netstat oder ss, um zu sehen, welcher Prozess den Port verwendet.
```
sudo netstat -tulnp | grep 50000
# oder
sudo ss -tulnp | grep 50000
```
Wenn ein anderer Prozess ihn verwendet, müssen Sie entweder Jenkins oder die andere Anwendung neu konfigurieren, um andere Ports zu verwenden.

Erweiterte Fehlerbehebung und Logs

Wenn Standardprüfungen das Problem nicht aufdecken, ist eine tiefergehende Untersuchung erforderlich.

Jenkins-Controller-Logs

Überprüfen Sie die Jenkins-Controller-Logs auf Fehler im Zusammenhang mit Agent-Verbindungen. Diese Logs können spezifische Fehlermeldungen liefern.

Speicherort: Normalerweise in $JENKINS_HOME/jenkins.log oder zugänglich über Jenkins verwalten -> System-Log.
Suchen Sie nach: Meldungen, die den Hostnamen des Agents, die IP-Adresse, Verbindungsversuche, JSch-Ausnahmen oder Fehler vom Typ "Verbindung abgelehnt" erwähnen.

Agent-Logs

Wenn der Agent läuft, aber als offline gemeldet wird, überprüfen Sie seine Logs auf Fehler.

JNLP-Agents: Der Agent-Prozess selbst könnte Logs auf seiner Konsole oder in einer bestimmten Logdatei ausgeben.
SSH-Agents: Logs könnten sich in $JENKINS_HOME/agent.log auf dem Agent-Rechner befinden oder sich auf sshd beziehen, wenn die Verbindung auf SSH-Ebene fehlschlägt.

Debug-Logging aktivieren

Bei sehr hartnäckigen Problemen kann die vorübergehende Aktivierung des Debug-Loggings für relevante Jenkins-Komponenten detailliertere Informationen liefern.

JNLP/Agent-Kommunikation: Möglicherweise müssen Sie Java-Systemeigenschaften anpassen oder die Jenkins-Logging-Konfiguration (Jenkins verwalten -> System-Log -> Log-Recorder) verwenden, um die Ausführlichkeit für hudson.slaves oder verwandte Pakete zu erhöhen.

Praktische Gewohnheiten, die wiederholte Ausfälle verhindern

Die Fehlerbehebung bei der Jenkins-Agent-Konnektivität erfordert einen systematischen Ansatz, der mit grundlegenden Netzwerkprüfungen beginnt und zu Jenkins-spezifischen Konfigurationen übergeht.

Netzwerk überprüfen: Beginnen Sie immer mit Ping und Telnet/nc, um die grundlegende Netzwerkerreichbarkeit und den Portzugriff sicherzustellen.
Firewalls überprüfen: Stellen Sie sicher, dass Firewalls sowohl auf dem Controller als auch auf dem Agenten sowie alle Netzwerk-Firewalls den Datenverkehr auf den erforderlichen Ports zulassen.
Anmeldeinformationen validieren: Überprüfen Sie SSH-Schlüssel, Benutzernamen und Passwörter doppelt.
Agent-Dienst bestätigen: Stellen Sie bei SSH-Agents sicher, dass sshd läuft und zugänglich ist.
Jenkins-Logs überwachen: Controller-Logs sind Ihre primäre Quelle, um Verbindungsfehler zu verstehen.
Bestimmte IPs verwenden: Konfigurieren Sie Firewalls und Jenkins nach Möglichkeit so, dass sie bestimmte IP-Adressen anstelle von breiten Bereichen oder 0.0.0.0 verwenden.

Wenn Sie diese Schritte befolgen, können Sie die meisten häufigen Jenkins-Agent-Konnektivitätsprobleme effektiv diagnostizieren und beheben und so Ihre CI/CD-Pipelines reibungslos am Laufen halten.

Die Offline-Meldung lesen, ohne zu raten

Das Wort "offline" ist zu allgemein, um allein damit Fehler zu beheben. Bevor Sie Jenkins-Einstellungen ändern, öffnen Sie die Agent-Seite und lesen Sie den genauen Grund, den Jenkins angibt. Es gibt einen großen Unterschied zwischen "Verbindung abgelehnt", "Zugriff verweigert", "Host-Key-Überprüfung fehlgeschlagen", "JNLP-Agent abgelehnt" und "Kanal wurde geschlossen". Sie alle enden mit einem Offline-Node, weisen aber auf verschiedene Ebenen hin.

Ich schreibe das Symptom normalerweise in einfacher Sprache auf: "Controller kann TCP-Port 22 nicht erreichen", "SSH-Anmeldung funktioniert, aber Java kann nicht starten", "Inbound-Agent startet, kann aber nicht zum Controller zurückrufen" oder "Agent verbindet sich und bricht dann während Builds ab." Dieser eine Satz hält die Untersuchung fokussiert.

Wenn der Agent noch nie verbunden war, vermuten Sie Konfiguration, DNS, Firewall, Anmeldeinformationen oder Startbefehl. Wenn er monatelang verbunden war und heute ausgefallen ist, überprüfen Sie aktuelle Änderungen: rotierte SSH-Schlüssel, ein Jenkins-Upgrade, ein Plugin-Update, eine neue Firewall-Regel, ein abgelaufenes Zertifikat, ein Agent-Image-Neubau oder eine Cloud-Netzwerkänderung. Der Zeitplan ist oft nützlicher als der Fehlertext.

SSH-Agents: Anmeldeprobleme von Startproblemen trennen

Testen Sie bei SSH-basierten Agents denselben Pfad, den Jenkins verwendet. Stellen Sie vom Controller-Host aus eine Verbindung als der in Jenkins konfigurierte Benutzer her:

ssh -vvv jenkins-agent-user@agent-hostname

Die ausführliche Ausgabe zeigt Ihnen, ob der Fehler vor der Authentifizierung, während der Authentifizierung oder nach der Anmeldung auftritt. Wenn SSH den Server nie erreicht, kann Jenkins das nicht beheben. Überprüfen Sie Routing, Sicherheitsgruppen, Netzwerk-ACLs, Host-Firewalls und den SSH-Daemon. Wenn SSH den Server erreicht, aber den Schlüssel ablehnt, überprüfen Sie die Anmeldeinformationen in Jenkins, die authorized_keys des Benutzers, Dateiberechtigungen und ob das Konto gesperrt ist.

Wenn die SSH-Anmeldung manuell funktioniert, Jenkins aber immer noch fehlschlägt, überprüfen Sie das entfernte Stammverzeichnis und den Java-Start. Jenkins benötigt ein beschreibbares Verzeichnis für die Remoting-Dateien, und der Agent-Benutzer benötigt die Berechtigung, dort Dateien zu erstellen. Ein häufiger Fehler ist, das entfernte Stammverzeichnis auf einen Pfad zu setzen, der root gehört oder von einem anderen Prozess bereinigt wird.

Führen Sie diese Prüfungen auf dem Agenten durch:

whoami
pwd
java -version
test -w /path/to/jenkins-agent && echo writable
df -h /path/to/jenkins-agent

Die Java-Version ist wichtig, da moderne Jenkins-Controller kompatible Java-Versionen auf den Agents erfordern. Die genaue Anforderung hängt von Ihrer Jenkins-Version ab. Überprüfen Sie daher die Jenkins-Dokumentation für Ihre Version, anstatt anzunehmen, dass ein altes Agent-Image noch gültig ist.

Inbound-Agents: Der Rückrufpfad ist die übliche Falle

Inbound-Agents werden oft verwendet, wenn der Controller kein SSH zum Agenten initiieren kann, z. B. bei Agents hinter NAT oder in eingeschränkten Netzwerken. Der Agent-Prozess startet außerhalb von Jenkins und verbindet sich zurück zum Controller. Das bedeutet, dass der Netzwerkpfad umgekehrt ist: Der Agent muss die Jenkins-URL auflösen und erreichen.

Testen Sie auf dem Agent-Host die Jenkins-URL genau wie konfiguriert:

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

Wenn Jenkins hinter einem Reverse-Proxy ist, bestätigen Sie, dass die öffentliche URL unter Jenkins verwalten > System korrekt ist. Eine falsche Jenkins-URL kann dazu führen, dass generierte Agent-Befehle auf einen internen Hostnamen verweisen, den der Agent nicht auflösen kann. Wenn der WebSocket-Modus für Inbound-Agents aktiviert ist, stellen Sie sicher, dass der Proxy WebSocket-Upgrade-Header unterstützt. Wenn Sie stattdessen den TCP-Inbound-Agent-Port verwenden, bestätigen Sie, dass der feste Port konfiguriert und vom Agent-Netzwerk aus erreichbar ist.

TLS-Probleme können wie Jenkins-Probleme aussehen. Wenn der Agent in einem minimalen Container-Image läuft, hat er möglicherweise Ihr internes CA-Zertifikat nicht. curl wird das normalerweise schnell aufdecken. Installieren Sie das CA-Zertifikat in das Agent-Image, anstatt die Zertifikatsprüfung zu deaktivieren.

Agents, die während Builds die Verbindung trennen

Ein Agent, der sich erfolgreich verbindet und dann während eines Builds die Verbindung abbricht, ist normalerweise kein grundlegendes Konnektivitätsproblem. Überprüfen Sie die Ressourcenauslastung und den Prozesslebenszyklus.

Überprüfen Sie, ob das Betriebssystem den Agent-Prozess beendet hat:

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

Überprüfen Sie auch den Speicherplatz. Jenkins-Remoting, Checkout, Testberichte und archivierte Artefakte benötigen alle Speicherplatz. Ein volles Workspace-Volume kann einen Agenten unzuverlässig erscheinen lassen, da der Remoting-Prozess keine temporären Dateien oder Logs schreiben kann.

Wenn Trennungen während großer Konsolenausgaben, Artefaktarchivierung oder Veröffentlichung von Testberichten auftreten, überprüfen Sie die Netzwerkstabilität und die Controller-Auslastung. Der Agent-Kanal ist eine Live-Verbindung. Lange Garbage-Collection-Pausen auf dem Controller, überlastete Proxys, Leerlauf-Zeitüberschreitungen und Paketverluste können ihn schließen. Überprüfen Sie bei Agents, die Load-Balancer oder Unternehmens-Proxys durchlaufen, die Einstellungen für Leerlauf-Zeitüberschreitungen und das Keepalive-Verhalten.

DNS- und Host-Key-Probleme

DNS-Änderungen sind leicht zu übersehen. Jenkins stellt möglicherweise eine Verbindung zu build-agent-01 her, während Ihr manueller Test eine IP-Adresse verwendet. Testen Sie den Hostnamen vom Controller aus:

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

Wenn der Hostname in die falsche Adresse aufgelöst wird, korrigieren Sie DNS oder die Agent-Konfiguration. Vermeiden Sie langfristige /etc/hosts-Patches, es sei denn, Sie haben einen klaren Eigentumsprozess, da sie zu unsichtbarer Infrastruktur werden.

Bei SSH-Agents schützt die Host-Key-Überprüfung Jenkins davor, eine Verbindung zu einem unerwarteten Rechner herzustellen. Wenn ein Agent neu aufgebaut wurde, hat sich sein Host-Key möglicherweise geändert. Deaktivieren Sie die Überprüfung nicht blind. Bestätigen Sie den Neubau, entfernen Sie den alten Schlüssel aus der known_hosts-Datei des Controller-Benutzers und akzeptieren Sie den neuen Schlüssel über die konfigurierte Jenkins-Strategie.

Eine Wiederherstellungs-Checkliste für Produktions-Agents

Wenn mehrere Agents gleichzeitig offline gehen, vermeiden Sie es, sie einzeln zu reparieren, bevor Sie die gemeinsame Ursache gefunden haben. Fragen Sie:

Wurde der Jenkins-Controller neu gestartet oder aktualisiert?
Wurden gemeinsame Anmeldeinformationen rotiert?
Hat sich ein Basis-Agent-Image geändert?
Wurde eine Firewall-, Proxy-, VPN- oder DNS-Änderung ausgerollt?
Befinden sich alle fehlgeschlagenen Agents im selben Subnetz, Cloud-Konto, Kubernetes-Namespace oder in derselben Verfügbarkeitszone?

Wenn nur ein Agent ausfällt, überprüfen Sie diesen Host. Wenn eine ganze Gruppe gemeinsam ausfällt, überprüfen Sie die gemeinsame Abhängigkeit. Das spart in größeren Jenkins-Flotten viel Zeit.