Comment sauvegarder et restaurer votre instance Jenkins
Sauvegardez et restaurez Jenkins en toute sécurité en archivant JENKINS_HOME, en préservant les secrets et en testant la récupération avant d'en avoir besoin.
Comment sauvegarder et restaurer votre instance Jenkins
Jenkins devient souvent le plan de contrôle pour vos builds, déploiements, identifiants et historique de versions. Si vous perdez $JENKINS_HOME lors d'une panne disque ou d'une mauvaise migration, vos pipelines CI/CD peuvent s'arrêter même si le package Jenkins lui-même est facile à réinstaller.
Ce guide vous montre quoi sauvegarder, comment créer une archive du système de fichiers en toute sécurité, et comment restaurer Jenkins sans casser les identifiants ni les droits de propriété des fichiers.
Comprendre le cœur : le répertoire $JENKINS_HOME
Chaque instance Jenkins repose sur un seul répertoire racine, appelé $JENKINS_HOME. Ce répertoire contient tous les fichiers de configuration, plugins, journaux et données de jobs. Sauvegarder Jenkins signifie fondamentalement sauvegarder le contenu de ce répertoire.
Selon votre méthode d'installation (par exemple, package Linux, conteneur Docker), l'emplacement de $JENKINS_HOME varie généralement :
- Linux (Installation par package) :
/var/lib/jenkins - Docker : Souvent monté sur un volume, par exemple
/var/jenkins_home - JAR autonome : Le répertoire où le processus Jenkins a été démarré, sauf indication contraire via des variables d'environnement.
Identification des composants de données critiques
Bien que la sauvegarde de l'intégralité du répertoire $JENKINS_HOME soit l'approche la plus simple, elle peut conduire à des archives extrêmement volumineuses si l'historique des builds et les données des espaces de travail sont inclus. Pour une sauvegarde rapide et efficace en cas de sinistre, vous devez vous assurer que les répertoires et fichiers suivants sont capturés :
| Composant | Chemin dans $JENKINS_HOME |
Objectif |
|---|---|---|
| Configuration globale | config.xml |
Fichier de configuration principal pour l'instance racine Jenkins. |
| Définitions des jobs | jobs/ |
Contient des sous-répertoires pour chaque job configuré, chacun avec son propre config.xml. |
| Utilisateurs et identifiants | users/ et credentials.xml |
Comptes utilisateurs, paramètres du domaine de sécurité et secrets stockés. |
| Clés de sécurité | secrets/ |
Clés de chiffrement essentielles pour déchiffrer les données sensibles comme les identifiants stockés. |
| Liste des plugins | plugins/ |
Contient les fichiers .hpi pour tous les plugins installés. |
| Définitions des nœuds | nodes/ |
Configurations de tous les agents de build connectés (si définis). |
Méthode 1 : La sauvegarde du système de fichiers (Recommandée)
La méthode la plus fiable pour sauvegarder Jenkins est de créer une archive cohérente et compressée des fichiers nécessaires pendant que le service est momentanément arrêté.
Étape 1 : Arrêter le service Jenkins
Pour garantir la cohérence des données et éviter les écritures partielles de fichiers pendant le processus de sauvegarde, le processus Jenkins doit être arrêté. Ne pas arrêter le service risque de créer une sauvegarde incomplète ou corrompue.
# Pour les systèmes utilisant systemd (la plupart des distributions Linux modernes)
sudo systemctl stop jenkins
# Ou, pour les systèmes utilisant la commande service
sudo service jenkins stop
Étape 2 : Créer l'archive de sauvegarde
Naviguez vers le répertoire parent de $JENKINS_HOME et utilisez tar pour créer une archive compressée. Il est fortement recommandé d'exclure les artefacts de build volumineux pour gagner de l'espace et du temps.
En supposant que $JENKINS_HOME est /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"
# Créer le répertoire cible s'il n'existe pas
mkdir -p $BACKUP_TARGET
# Créer l'archive, en excluant l'historique des builds et les espaces de travail
sudo tar -czvf "${BACKUP_TARGET}/${ARCHIVE_NAME}" \
--exclude="${JENKINS_HOME}/workspace" \
--exclude="${JENKINS_HOME}/caches" \
--exclude="${JENKINS_HOME}/jobs/*/builds" \
"${JENKINS_HOME}"
Astuce : Inclure l'historique des builds
Si la conservation de l'historique des builds (
jobs/*/builds) est critique, vous pouvez supprimer le drapeau--excludecorrespondant. Cependant, préparez-vous à des tailles d'archive pouvant atteindre des centaines de gigaoctets.
Étape 3 : Vérifier et stocker hors site
Une fois l'archive créée, testez qu'elle peut être lue avant de lui faire confiance :
tar -tzf "${BACKUP_TARGET}/${ARCHIVE_NAME}" >/dev/null
Transférez-la ensuite vers un emplacement de stockage externe, comme un bucket S3 ou un système de sauvegarde réseau, afin qu'une panne de disque local ne détruise pas à la fois Jenkins et sa sauvegarde.
Étape 4 : Redémarrer Jenkins
sudo systemctl start jenkins
Méthode 2 : Utilisation du plugin de sauvegarde Jenkins (Solution partielle)
Bien que des plugins comme ThinBackup ou Backup Plugin existent, ils ne capturent souvent que les fichiers de configuration (config.xml) et peuvent ne pas gérer correctement les fichiers volumineux ou tous les éléments de sécurité nécessaires. Ceux-ci sont généralement adaptés pour sauvegarder les configurations de jobs uniquement et ne doivent pas être utilisés pour une stratégie complète et sécurisée de reprise après sinistre.
Restauration de votre instance Jenkins
La restauration consiste à copier les données sauvegardées dans le répertoire $JENKINS_HOME de la machine cible et à s'assurer que les permissions des fichiers sont correctes avant de démarrer le service.
Étape 1 : Préparer l'environnement cible
Assurez-vous que le système cible (ou le système réparé) a Jenkins installé, mais gardez le service arrêté.
sudo systemctl stop jenkins
Étape 2 : Effacer les données Jenkins existantes (Optionnel mais recommandé)
Si vous restaurez sur une machine qui hébergeait auparavant Jenkins, videz le contenu existant de $JENKINS_HOME pour garantir un environnement propre.
# Soyez prudent avec la commande 'rm -rf' !
sudo rm -rf /var/lib/jenkins/*
Étape 3 : Extraire l'archive de sauvegarde
Copiez l'archive compressée (jenkins_backup_latest.tar.gz) sur la machine cible et extrayez-la dans le répertoire $JENKINS_HOME. Le drapeau -C spécifie le répertoire cible pour l'extraction.
# En supposant que l'archive est dans /tmp et que JENKINS_HOME est /var/lib/jenkins
sudo tar -xzvf /tmp/jenkins_backup_latest.tar.gz -C /var/lib/
# Remarque : Si la commande tar incluait le répertoire parent dans l'archive, ajustez le chemin.
# Le résultat doit être que le contenu de l'archive remplace le contenu de /var/lib/jenkins
Étape 4 : Vérifier et corriger les permissions
C'est l'étape la plus critique après la restauration. Si la propriété des fichiers est incorrecte, Jenkins ne démarrera pas ou ne fonctionnera pas de manière sécurisée. Vous devez définir la propriété de manière récursive sur l'utilisateur et le groupe sous lesquels le service Jenkins s'exécute (souvent 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
Étape 5 : Démarrer Jenkins et vérifier
Démarrez le service et surveillez les journaux pour vous assurer d'un démarrage réussi.
sudo systemctl start jenkins
# Surveiller les journaux de démarrage
sudo tail -f /var/log/jenkins/jenkins.log
Après un démarrage réussi, vérifiez que tous les jobs, utilisateurs et plugins installés sont présents et fonctionnent correctement.
Bonnes pratiques pour les sauvegardes automatisées
Pour aller au-delà des sauvegardes manuelles, mettez en œuvre l'automatisation à l'aide d'outils système et d'une gestion de configuration externe.
1. Utiliser des tâches Cron
Planifiez l'exécution du script de sauvegarde (Étapes 1 et 2 de la Méthode 1) quotidiennement ou chaque nuit à l'aide de cron ou d'un planificateur similaire. Assurez-vous que la tâche cron s'exécute en tant qu'utilisateur disposant des autorisations appropriées pour arrêter et démarrer le service Jenkins et lire/écrire dans le répertoire $JENKINS_HOME.
2. Configuration en tant que code (CasC)
Envisagez d'adopter Jenkins Configuration as Code (CasC). CasC définit les paramètres, les jobs et les plugins de Jenkins à l'aide de fichiers YAML déclaratifs. En stockant ces fichiers YAML dans un référentiel de contrôle de source séparé (comme Git), votre configuration devient portable et versionnée, simplifiant considérablement l'exigence de sauvegarde de base.
À retenir
Considérez une sauvegarde Jenkins comme utile seulement après avoir testé une restauration. Un bon plan de récupération préserve config.xml, jobs/, plugins/, users/, credentials.xml et secrets/, puis vérifie que les jobs peuvent s'exécuter sur une instance propre.
Avertissement : Sécurisation des identifiants
Lors de la restauration d'une instance, assurez-vous que le répertoire
secrets/est présent et correct. Si Jenkins ne trouve pas les clés utilisées pour chiffrer les identifiants (comme les clés API ou les mots de passe), ces identifiants deviendront inutilisables et devront être saisis à nouveau manuellement.