So sichern und stellen Sie Ihre Jenkins-Instanz wieder her

Jenkins wird oft zur Steuerungsebene für Ihre Builds, Bereitstellungen, Anmeldeinformationen und Release-Historie. Wenn Sie $JENKINS_HOME während eines Festplattenfehlers oder einer fehlerhaften Migration verlieren, können Ihre CI/CD-Pipelines stoppen, selbst wenn das Jenkins-Paket selbst einfach neu installiert werden kann.

Diese Anleitung zeigt Ihnen, was Sie sichern müssen, wie Sie ein Dateisystemarchiv sicher erstellen und wie Sie Jenkins wiederherstellen, ohne Anmeldeinformationen oder Dateiberechtigungen zu beschädigen.

Das Kernstück verstehen: Das $JENKINS_HOME-Verzeichnis

Jede Jenkins-Instanz basiert auf einem einzigen Stammverzeichnis, das als $JENKINS_HOME bezeichnet wird. Dieses Verzeichnis enthält alle Konfigurationsdateien, Plugins, Protokolle und Auftragsdaten. Jenkins zu sichern bedeutet im Wesentlichen, den Inhalt dieses Verzeichnisses zu sichern.

Abhängig von Ihrer Installationsmethode (z. B. Linux-Paket, Docker-Container) variiert der Speicherort von $JENKINS_HOME typischerweise:

• Linux (Paketinstallation): /var/lib/jenkins
• Docker: Oft auf ein Volume gemountet, z. B. /var/jenkins_home
• Eigenständiges JAR: Das Verzeichnis, in dem der Jenkins-Prozess gestartet wurde, sofern nicht über Umgebungsvariablen angegeben.

Identifizieren kritischer Datenkomponenten

Das Sichern des gesamten $JENKINS_HOME-Verzeichnisses ist zwar der einfachste Ansatz, kann aber zu extrem großen Archiven führen, wenn Build-Verlauf und Arbeitsbereichsdaten enthalten sind. Für eine schnelle und effiziente Notfallwiederherstellung müssen Sie sicherstellen, dass die folgenden Verzeichnisse und Dateien erfasst werden:

Komponente	Pfad innerhalb von $JENKINS_HOME	Zweck
Globale Konfiguration	config.xml	Primäre Konfigurationsdatei für die Jenkins-Root-Instanz.
Auftragsdefinitionen	jobs/	Enthält Unterverzeichnisse für jeden konfigurierten Auftrag, jeweils mit eigener config.xml.
Benutzer und Anmeldeinformationen	users/ und credentials.xml	Benutzerkonten, Sicherheitsbereichseinstellungen und gespeicherte Geheimnisse.
Sicherheitsschlüssel	secrets/	Verschlüsselungsschlüssel, die zum Entschlüsseln sensibler Daten wie gespeicherter Anmeldeinformationen erforderlich sind.
Plugin-Liste	plugins/	Enthält die .hpi-Dateien aller installierten Plugins.
Knotendefinitionen	nodes/	Konfigurationen für alle verbundenen Build-Agenten (falls definiert).

---

Methode 1: Die Dateisystemsicherung (Empfohlen)

Die zuverlässigste Methode zum Sichern von Jenkins besteht darin, ein konsistentes, komprimiertes Archiv der erforderlichen Dateien zu erstellen, während der Dienst kurzzeitig gestoppt wird.

Schritt 1: Stoppen Sie den Jenkins-Dienst

Um die Datenkonsistenz zu gewährleisten und partielle Dateischreibvorgänge während des Sicherungsvorgangs zu verhindern, muss der Jenkins-Prozess angehalten werden. Wenn der Dienst nicht gestoppt wird, riskieren Sie ein unvollständiges oder beschädigtes Backup.

# Für Systeme mit systemd (die meisten modernen Linux-Distributionen)
sudo systemctl stop jenkins

# Oder für Systeme mit dem service-Befehl
sudo service jenkins stop

Schritt 2: Erstellen Sie das Sicherungsarchiv

Navigieren Sie zum übergeordneten Verzeichnis von $JENKINS_HOME und verwenden Sie tar, um ein komprimiertes Archiv zu erstellen. Es wird dringend empfohlen, die großen Build-Artefakte auszuschließen, um Speicherplatz und Zeit zu sparen.

Angenommen, $JENKINS_HOME ist /var/lib/jenkins:

JENKINS_HOME="/var/lib/jenkins"
BACKUP_TARGET="/mnt/backups/jenkins"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
ARCHIVE_NAME="jenkins_backup_${TIMESTAMP}.tar.gz"

# Erstellen Sie das Zielverzeichnis, falls es nicht existiert
mkdir -p $BACKUP_TARGET

# Erstellen Sie das Archiv unter Ausschluss von Build-Verlauf und Arbeitsbereichen
sudo tar -czvf "${BACKUP_TARGET}/${ARCHIVE_NAME}" \
    --exclude="${JENKINS_HOME}/workspace" \
    --exclude="${JENKINS_HOME}/caches" \
    --exclude="${JENKINS_HOME}/jobs/*/builds" \
    "${JENKINS_HOME}"

Tipp: Build-Verlauf einschließen

Wenn die Beibehaltung des Build-Verlaufs (jobs/*/builds) kritisch ist, können Sie das entsprechende --exclude-Flag entfernen. Seien Sie jedoch darauf vorbereitet, dass die Archivgrößen potenziell Hunderte von Gigabyte erreichen können.

Schritt 3: Überprüfen und extern speichern

Sobald das Archiv erstellt ist, testen Sie, ob es gelesen werden kann, bevor Sie ihm vertrauen:

tar -tzf "${BACKUP_TARGET}/${ARCHIVE_NAME}" >/dev/null

Übertragen Sie es dann an einen externen Speicherort, z. B. einen S3-Bucket oder ein Netzwerk-Backup-System, damit ein lokaler Festplattenfehler nicht sowohl Jenkins als auch sein Backup zerstört.

Schritt 4: Starten Sie Jenkins neu

sudo systemctl start jenkins

Methode 2: Nutzung des Jenkins-Backup-Plugins (Teillösung)

Obwohl Plugins wie ThinBackup oder Backup Plugin existieren, erfassen sie oft nur Konfigurationsdateien (config.xml) und können große Dateien oder alle notwendigen Sicherheitselemente nicht robust handhaben. Diese sind im Allgemeinen nur zum Sichern von Auftragskonfigurationen geeignet und sollten nicht für eine vollständige, sichere Notfallwiederherstellungsstrategie verwendet werden.

Wiederherstellen Ihrer Jenkins-Instanz

Die Wiederherstellung umfasst das Kopieren der gesicherten Daten in das $JENKINS_HOME-Verzeichnis des Zielrechners und die Sicherstellung korrekter Dateiberechtigungen vor dem Starten des Dienstes.

Schritt 1: Bereiten Sie die Zielumgebung vor

Stellen Sie sicher, dass auf dem Zielsystem (oder dem reparierten System) Jenkins installiert ist, aber halten Sie den Dienst gestoppt.

sudo systemctl stop jenkins

Schritt 2: Löschen Sie vorhandene Jenkins-Daten (optional, aber empfohlen)

Wenn Sie auf einem Rechner wiederherstellen, der zuvor Jenkins gehostet hat, löschen Sie den vorhandenen Inhalt von $JENKINS_HOME, um eine saubere Umgebung zu gewährleisten.

# Seien Sie vorsichtig mit dem Befehl 'rm -rf'!
sudo rm -rf /var/lib/jenkins/*

Schritt 3: Extrahieren Sie das Sicherungsarchiv

Kopieren Sie das komprimierte Archiv (jenkins_backup_latest.tar.gz) auf den Zielrechner und extrahieren Sie es in das $JENKINS_HOME-Verzeichnis. Das Flag -C gibt das Zielverzeichnis für die Extraktion an.

# Angenommen, das Archiv befindet sich in /tmp und JENKINS_HOME ist /var/lib/jenkins
sudo tar -xzvf /tmp/jenkins_backup_latest.tar.gz -C /var/lib/

# Hinweis: Wenn der tar-Befehl das übergeordnete Verzeichnis im Archiv enthalten hat, passen Sie den Pfad an.
# Das Ergebnis sollte sein, dass der Inhalt des Archivs den Inhalt von /var/lib/jenkins ersetzt

Schritt 4: Überprüfen und korrigieren Sie die Berechtigungen

Dies ist der kritischste Schritt nach der Wiederherstellung. Wenn die Dateibesitzer falsch sind, wird Jenkins nicht starten oder sicher arbeiten. Sie müssen die Besitzer rekursiv auf den Benutzer und die Gruppe setzen, unter denen der Jenkins-Dienst läuft (oft jenkins:jenkins).

JENKINS_HOME="/var/lib/jenkins"
JENKINS_USER="jenkins"
JENKINS_GROUP="jenkins"

sudo chown -R $JENKINS_USER:$JENKINS_GROUP $JENKINS_HOME
sudo find "$JENKINS_HOME" -type d -exec chmod 755 {} \;
sudo find "$JENKINS_HOME" -type f -exec chmod 644 {} \;
sudo chmod -R go-rwx "$JENKINS_HOME/secrets" "$JENKINS_HOME/users" 2>/dev/null || true

Schritt 5: Starten Sie Jenkins und überprüfen Sie

Starten Sie den Dienst und überwachen Sie die Protokolle, um einen erfolgreichen Start sicherzustellen.

sudo systemctl start jenkins

# Überwachen Sie die Startprotokolle
sudo tail -f /var/log/jenkins/jenkins.log

Überprüfen Sie nach erfolgreichem Start, ob alle Aufträge, Benutzer und installierten Plugins vorhanden sind und ordnungsgemäß funktionieren.

Best Practices für automatisierte Backups

Um über manuelle Backups hinauszugehen, implementieren Sie die Automatisierung mit Systemtools und externem Konfigurationsmanagement.

1. Nutzen Sie Cron-Jobs

Planen Sie das Sicherungsskript (Schritte 1 und 2 aus Methode 1) mit cron oder einem ähnlichen Planer für tägliche oder nächtliche Ausführungen. Stellen Sie sicher, dass der Cron-Job als Benutzer mit entsprechenden Berechtigungen zum Stoppen und Starten des Jenkins-Dienstes sowie zum Lesen/Schreiben in das $JENKINS_HOME-Verzeichnis ausgeführt wird.

2. Konfiguration als Code (CasC)

Erwägen Sie die Einführung von Jenkins Configuration as Code (CasC). CasC definiert Jenkins-Einstellungen, Aufträge und Plugins mit deklarativen YAML-Dateien. Durch die Speicherung dieser YAML-Dateien in einem separaten Quellcode-Repository (wie Git) wird Ihre Konfiguration portabel und versioniert, was die grundlegende Backup-Anforderung drastisch vereinfacht.

Fazit

Behandeln Sie ein Jenkins-Backup nur dann als nützlich, wenn Sie eine Wiederherstellung getestet haben. Ein guter Wiederherstellungsplan bewahrt config.xml, jobs/, plugins/, users/, credentials.xml und secrets/ und überprüft dann, ob Aufträge auf einer sauberen Instanz ausgeführt werden können.

Warnung: Sichern von Anmeldeinformationen

Stellen Sie bei der Wiederherstellung einer Instanz sicher, dass das Verzeichnis secrets/ vorhanden und korrekt ist. Wenn Jenkins die Schlüssel nicht finden kann, die zum Verschlüsseln von Anmeldeinformationen (wie API-Schlüssel oder Passwörter) verwendet wurden, werden diese Anmeldeinformationen unbrauchbar und müssen manuell neu eingegeben werden.