Recharger en toute sécurité les configurations Jenkins sans nécessiter de redémarrage

Recharger la configuration Jenkins semble inoffensif jusqu'à ce que vous le fassiez sur un contrôleur occupé et découvriez que toutes les modifications ne peuvent pas être appliquées proprement pendant que des tâches sont en cours. La bonne commande dépend de ce qui a changé.

Si vous avez modifié des fichiers XML dans JENKINS_HOME, restauré des tâches à partir d'une sauvegarde ou modifié des fichiers en dehors de l'interface web, Jenkins peut recharger la configuration depuis le disque. Si vous avez installé ou mis à jour des plugins, modifié les options Java ou devez rafraîchir l'état d'exécution, un redémarrage sécurisé est généralement le meilleur outil. Ce sont des opérations différentes.

Le raccourci trompeur à éviter est System.exit(10) dans la console de scripts. Il peut amener un superviseur de processus, un conteneur de servlets ou un wrapper de service à redémarrer Jenkins selon la façon dont Jenkins est lancé, mais ce n'est pas une commande propre de "rechargement de configuration". Cela peut interrompre le travail et masque l'intention. Utilisez plutôt le CLI Jenkins ou les actions de gestion intégrées.

Recharger la configuration depuis le disque avec le CLI

La commande la plus claire est reload-configuration :

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

Cela demande à Jenkins de jeter la configuration chargée et de la relire depuis le disque. C'est utile après des modifications contrôlées de fichiers, comme la restauration d'une configuration de tâche ou l'application d'une configuration générée par automatisation.

Avant de l'exécuter, vérifiez trois choses :

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

Le compte nécessite une autorisation administrative pour le rechargement de configuration. N'utilisez pas un jeton d'administration personnel provenant de l'ordinateur portable de quelqu'un pour l'automatisation courante. Utilisez un compte administrateur géré, conservez le jeton dans un coffre sécurisé et faites-le tourner selon votre politique.

Si vous préférez l'interface web, utilisez Manage Jenkins et l'option de rechargement lorsqu'elle est disponible dans votre version de Jenkins et les composants installés. Le CLI est plus facile à auditer car la commande peut figurer dans un runbook.

Quand le redémarrage sécurisé est le meilleur choix

Un redémarrage sécurisé attend la fin des builds en cours, puis redémarre Jenkins. Il est plus lent qu'un rechargement, mais il est plus honnête lorsque l'état d'exécution doit être reconstruit.

Utilisez le redémarrage sécurisé après l'installation ou la mise à jour de plugins, les modifications des options Java, les mises à jour du cœur de Jenkins, ou un comportement qui n'apparaît qu'après un redémarrage complet du contrôleur.

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

Vous pouvez également utiliser le point d'accès /safeRestart si votre environnement le permet, mais la forme CLI est plus facile à standardiser.

Ne promettez pas une interruption de service nulle. Un rechargement peut affecter brièvement l'interface utilisateur, et un redémarrage sécurisé redémarre intentionnellement le contrôleur après la vidange des builds. Si les agents se déconnectent ou si les plugins se comportent mal, les utilisateurs peuvent le remarquer. Planifiez l'opération lorsque le rayon d'impact est acceptable.

Un runbook de rechargement plus sûr

D'abord, annoncez la fenêtre de maintenance, même si elle est courte. Ensuite, vérifiez ce qui est en cours d'exécution :

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

Pour une vérification rapide de la file d'attente, utilisez Groovy via le CLI :

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" groovy = <<'EOF'
Jenkins.instance.queue.items.each { item ->
  println "En file d'attente : ${item.task.fullDisplayName}"
}
Jenkins.instance.computers.each { computer ->
  computer.executors.findAll { it.isBusy() }.each { executor ->
    println "En cours d'exécution sur ${computer.displayName} : ${executor.currentExecutable}"
  }
}
EOF

Sauvegardez la configuration que vous allez utiliser. Au minimum, ayez une sauvegarde récente de JENKINS_HOME, en particulier config.xml, les répertoires de tâches, les métadonnées d'identifiants et l'état des plugins. Soyez prudent avec les fichiers d'identifiants ; protégez les sauvegardes comme des secrets.

Exécutez le rechargement :

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

Ensuite, vérifiez que le contrôleur répond :

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

Consultez le journal système et une tâche représentative avant de déclarer le travail terminé. Un rechargement qui réussit peut toujours exposer un mauvais XML de tâche, un plugin manquant ou un problème de permission.

À propos des scripts de rechargement Groovy

La console de scripts est puissante car elle s'exécute à l'intérieur du contrôleur Jenkins. C'est aussi pourquoi elle mérite de la prudence. Tout utilisateur de la console de scripts peut lire des secrets, modifier des tâches, désactiver les contrôles de sécurité ou casser le contrôleur.

Si vous avez besoin de Groovy pour l'inspection, gardez-le en lecture seule et court. Par exemple :

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

Évitez les appels de rechargement internes non documentés, sauf si vous les avez testés avec votre version de Jenkins et vos plugins. Les API internes peuvent changer, et les méthodes de rechargement spécifiques aux plugins peuvent ne pas recharger l'état qui vous intéresse.

Pour les configurations en tant que code, utilisez le mécanisme de rechargement documenté du plugin plutôt qu'un rechargement Jenkins générique. JCasC a son propre modèle et comportement de validation, et un fichier de configuration qui semble correct sur le disque peut toujours échouer lors de l'application.

Que faire si le rechargement échoue

Si Jenkins revient avec des tâches manquantes, des vues cassées ou des erreurs de plugins, ne continuez pas à cliquer sur rechargement. Capturez le journal système, notez l'heure et comparez les fichiers modifiés avec la sauvegarde. Les causes courantes sont un XML mal formé, une configuration de tâche qui référence un plugin qui n'est plus installé, ou des modifications manuelles effectuées alors que Jenkins écrit encore des fichiers.

Si l'interface utilisateur est instable mais que le processus est en cours d'exécution, un redémarrage sécurisé peut effacer l'état transitoire. Si la configuration est réellement erronée, restaurez d'abord les fichiers précédents, puis rechargez ou redémarrez.

Le modèle le plus sûr est simple : utilisez reload-configuration pour les modifications de configuration sur disque, utilisez safe-restart pour les modifications d'exécution et de plugins, et réservez la console de scripts pour des scripts administratifs délibérés que vous pouvez expliquer ligne par ligne.