Jenkins-Konfigurationen sicher neu laden, ohne einen Neustart zu erfordern

Das Neuladen der Jenkins-Konfiguration klingt harmlos, bis Sie es auf einem ausgelasteten Controller durchführen und feststellen, dass nicht jede Änderung sauber übernommen werden kann, während Jobs laufen. Der richtige Befehl hängt davon ab, was sich geändert hat.

Wenn Sie XML-Dateien in JENKINS_HOME bearbeitet, Jobs aus einem Backup wiederhergestellt oder Dateien außerhalb der Weboberfläche geändert haben, kann Jenkins die Konfiguration von der Festplatte neu laden. Wenn Sie Plugins installiert oder aktualisiert, Java-Optionen geändert oder den Laufzeitzustand aktualisiert haben, ist ein sicherer Neustart in der Regel das bessere Werkzeug. Das sind unterschiedliche Vorgänge.

Die irreführende Abkürzung, die Sie vermeiden sollten, ist System.exit(10) in der Script Console. Dies kann je nach Startart von Jenkins dazu führen, dass ein Prozess-Supervisor, Servlet-Container oder Service-Wrapper Jenkins neu startet, aber es ist kein sauberer Befehl zum Neuladen der Konfiguration. Es kann die Arbeit unterbrechen und verbirgt die Absicht. Verwenden Sie stattdessen die Jenkins-CLI oder die integrierten Verwaltungsaktionen.

Konfiguration von der Festplatte mit der CLI neu laden

Der klarste Befehl ist reload-configuration:

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration

Dies weist Jenkins an, die geladene Konfiguration zu verwerfen und erneut von der Festplatte zu lesen. Dies ist nützlich nach kontrollierten Dateiänderungen, wie dem Wiederherstellen einer Job-Konfiguration oder dem Anwenden von Konfigurationen, die durch Automatisierung generiert wurden.

Überprüfen Sie vor der Ausführung drei Dinge:

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" who-am-i
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs >/dev/null

Das Konto benötigt Administratorberechtigungen für das Neuladen der Konfiguration. Verwenden Sie für die routinemäßige Automatisierung kein persönliches Admin-Token von einem Laptop. Verwenden Sie ein verwaltetes Admin-Konto, bewahren Sie das Token in einem Geheimnisspeicher auf und rotieren Sie es gemäß Ihrer Richtlinie.

Wenn Sie die Weboberfläche bevorzugen, verwenden Sie Manage Jenkins und die Neuladeoption, sofern in Ihrer Jenkins-Version und den installierten Komponenten verfügbar. Die CLI ist einfacher zu prüfen, da der Befehl in einem Runbook leben kann.

Wann ein sicherer Neustart die bessere Wahl ist

Ein sicherer Neustart wartet auf das Ende laufender Builds und startet dann Jenkins neu. Er ist langsamer als ein Neuladen, aber ehrlicher, wenn der Laufzeitzustand neu aufgebaut werden muss.

Verwenden Sie den sicheren Neustart nach Plugin-Installation oder -Upgrade, Änderungen der Java-Optionen, Jenkins-Core-Upgrades oder Verhalten, das erst nach einem vollständigen Controller-Neustart auftritt.

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" safe-restart

Sie können auch den /safeRestart-Endpunkt verwenden, wenn Ihre Umgebung dies zulässt, aber die CLI-Form ist einfacher zu standardisieren.

Versprechen Sie keine Null-Ausfallzeit. Ein Neuladen kann die Benutzeroberfläche kurzzeitig beeinträchtigen, und ein sicherer Neustart startet den Controller absichtlich neu, nachdem die Builds abgeschlossen sind. Wenn Agents die Verbindung trennen oder Plugins sich schlecht verhalten, können Benutzer dies bemerken. Planen Sie den Vorgang, wenn der Schadensradius akzeptabel ist.

Ein sichereres Runbook zum Neuladen

Kündigen Sie zuerst das Wartungsfenster an, auch wenn es kurz ist. Überprüfen Sie dann, was läuft:

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs

Für eine schnelle Warteschlangenprüfung verwenden Sie Groovy über die CLI:

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" groovy = <<'EOF'
Jenkins.instance.queue.items.each { item ->
  println "Queued: ${item.task.fullDisplayName}"
}
Jenkins.instance.computers.each { computer ->
  computer.executors.findAll { it.isBusy() }.each { executor ->
    println "Running on ${computer.displayName}: ${executor.currentExecutable}"
  }
}
EOF

Sichern Sie die Konfiguration, die Sie verwenden werden. Halten Sie mindestens ein aktuelles Backup von JENKINS_HOME bereit, insbesondere config.xml, Job-Verzeichnisse, Anmeldedaten-Metadaten und Plugin-Zustand. Seien Sie vorsichtig mit Anmeldedaten-Dateien; schützen Sie Backups als Geheimnisse.

Führen Sie das Neuladen aus:

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration

Überprüfen Sie dann, ob der Controller antwortet:

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" who-am-i
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs >/dev/null

Überprüfen Sie das Systemprotokoll und einen repräsentativen Job, bevor Sie die Arbeit als erledigt betrachten. Ein erfolgreich zurückgegebenes Neuladen kann dennoch eine fehlerhafte Job-XML, ein fehlendes Plugin oder ein Berechtigungsproblem offenlegen.

Über Groovy-Neuladeskripte

Die Script Console ist leistungsstark, da sie innerhalb des Jenkins-Controllers ausgeführt wird. Das ist auch der Grund, warum Vorsicht geboten ist. Jeder Script Console-Benutzer kann Geheimnisse lesen, Jobs ändern, Sicherheitskontrollen deaktivieren oder den Controller beschädigen.

Wenn Sie Groovy zur Überprüfung benötigen, halten Sie es schreibgeschützt und kurz. Zum Beispiel:

println Jenkins.instance.version
println Jenkins.instance.items.size()
println Jenkins.instance.queue.items.size()

Vermeiden Sie undokumentierte interne Neuladeaufrufe, es sei denn, Sie haben sie gegen Ihre Jenkins-Version und Plugins getestet. Interne APIs können sich ändern, und plugin-spezifische Neulademethoden laden möglicherweise nicht den Zustand, der Ihnen wichtig ist.

Für Configuration as Code-Setups verwenden Sie den dokumentierten Neulademechanismus des Plugins anstelle eines generischen Jenkins-Neuladens. JCasC hat sein eigenes Modell und Validierungsverhalten, und eine Konfigurationsdatei, die auf der Festplatte korrekt aussieht, kann dennoch beim Anwenden fehlschlagen.

Was tun, wenn das Neuladen schiefgeht

Wenn Jenkins mit fehlenden Jobs, defekten Ansichten oder Plugin-Fehlern zurückkommt, klicken Sie nicht weiter auf Neuladen. Erfassen Sie das Systemprotokoll, notieren Sie die Uhrzeit und vergleichen Sie die geänderten Dateien mit dem Backup. Häufige Ursachen sind fehlerhaftes XML, eine Job-Konfiguration, die auf ein nicht mehr installiertes Plugin verweist, oder manuelle Bearbeitungen, während Jenkins noch Dateien schreibt.

Wenn die Benutzeroberfläche instabil ist, der Prozess jedoch läuft, kann ein sicherer Neustart den vorübergehenden Zustand löschen. Wenn die Konfiguration tatsächlich fehlerhaft ist, stellen Sie zuerst die vorherigen Dateien wieder her und laden Sie dann neu oder starten Sie neu.

Das sicherste Muster ist einfach: Verwenden Sie reload-configuration für Konfigurationsänderungen auf der Festplatte, verwenden Sie safe-restart für Laufzeit- und Plugin-Änderungen, und reservieren Sie die Script Console für bewusste administrative Skripte, die Sie Zeile für Zeile erklären können.