Résolution des conflits de plugins Jenkins : meilleures pratiques et solutions

Les plugins Jenkins sont utiles, mais ils constituent également l'un des moyens les plus simples de rendre un contrôleur stable imprévisible. Une mise à jour de plugin peut modifier les dépendances, les étapes de pipeline, le comportement de sécurité, les formulaires d'interface utilisateur et les exigences minimales du noyau Jenkins. Lorsque les builds commencent à échouer juste après un changement de plugin, traitez-le comme un changement de production nécessitant des preuves, des options de retour arrière et une isolation minutieuse.

La question pratique est simple : est-ce qu'un plugin a échoué, un plugin de dépendance a échoué, ou le noyau Jenkins et l'ensemble des plugins ont-ils dérivé hors de compatibilité ?

Comprendre les conflits de plugins Jenkins

Les conflits de plugins proviennent généralement d'une inadéquation dans les bibliothèques partagées, de versions incompatibles ou de différences architecturales profondes. Le mécanisme de chargement des plugins de Jenkins, bien que robuste, peut parfois rencontrer des difficultés lorsque plusieurs plugins tentent d'utiliser différentes versions de la même bibliothèque sous-jacente ou lorsque la structure interne d'un plugin entre en conflit avec une autre. Cela conduit à ce que l'on appelle souvent "l'enfer des dépendances".

Causes courantes des conflits :

Dépendances incompatibles : La cause la plus fréquente. Le plugin A nécessite la bibliothèque X version 1.0, tandis que le plugin B nécessite la bibliothèque X version 2.0. Lorsque les deux sont présents, un plugin peut échouer ou se comporter de manière erratique.
Inadéquation de version du noyau Jenkins : Un plugin peut être incompatible avec votre version actuelle du noyau Jenkins, ou vice-versa. Les versions plus récentes de Jenkins introduisent souvent des changements qui cassent les plugins plus anciens, et les versions plus anciennes de Jenkins peuvent manquer de fonctionnalités dont les plugins plus récents ont besoin.
Dépendances transitives : Des conflits peuvent survenir à partir de dépendances indirectes. Le plugin A dépend du plugin C, et le plugin B dépend également du plugin C, mais ils nécessitent des versions différentes ou ont des exigences conflictuelles pour le plugin C.
Problèmes de chargeur de classes : Jenkins utilise un système de chargeur de classes hiérarchique. Parfois, des classes de différentes versions de la même bibliothèque peuvent être chargées par différents chargeurs de classes, conduisant à java.lang.LinkageError ou java.lang.IncompatibleClassChangeError si elles tentent d'interagir.

Identifier les conflits de plugins

La première étape pour résoudre un conflit est de l'identifier. Les conflits se manifestent de diverses manières, allant de messages d'erreur évidents à des problèmes subtils et difficiles à diagnostiquer.

Où chercher des indices :

Journaux système Jenkins : C'est votre source d'information principale. Vérifiez JENKINS_HOME/logs/jenkins.log (ou catalina.out si vous utilisez Tomcat). Recherchez les traces de pile contenant :
- java.lang.NoClassDefFoundError : Une classe attendue n'a pas pu être trouvée. Indique souvent une dépendance manquante ou incompatible.
- java.lang.NoSuchMethodError : Une méthode attendue n'a pas pu être trouvée. Se produit généralement lorsqu'une bibliothèque ou une classe est chargée, mais qu'il s'agit d'une version plus ancienne qui ne possède pas la méthode qu'un plugin tente d'appeler.
- java.lang.AbstractMethodError : Similaire à NoSuchMethodError, pointe souvent vers un changement d'interface.
- java.lang.LinkageError (par exemple, java.lang.IllegalAccessError, java.lang.IncompatibleClassChangeError) : Se produit lorsqu'une classe a été chargée, mais que sa définition a changé de manière incompatible entre les versions, ou que les règles d'accès sont violées.
- Messages indiquant des échecs de démarrage de plugin ou des arrêts inattendus.
1. Notifications de l'interface utilisateur Jenkins : La section Gérer Jenkins -> Gérer les plugins affiche souvent des avertissements concernant des plugins obsolètes ou incompatibles, ou des plugins qui n'ont pas pu être chargés.
2. Échecs de build : Si les builds commencent à échouer immédiatement après l'installation ou la mise à jour d'un plugin, en particulier avec ClassNotFoundException ou des erreurs similaires dans la sortie de la console de build, un conflit de plugin est un suspect sérieux.
3. Comportement inattendu : Des fonctionnalités cessent de fonctionner, des éléments d'interface disparaissent ou des options de configuration deviennent indisponibles. Ceux-ci peuvent être des symptômes d'un conflit plus profond.

Stratégies de résolution

Une fois qu'un conflit est suspecté, une approche systématique est nécessaire pour le résoudre.

1. Les bases : Mettre à jour, rétrograder, désactiver

Mettre à jour tous les plugins : Souvent, le simple fait de mettre à jour tous les plugins vers leurs dernières versions peut résoudre les conflits, car les versions plus récentes incluent fréquemment des corrections de dépendances et des améliorations de compatibilité. Allez dans Gérer Jenkins -> Gérer les plugins -> onglet Mises à jour, sélectionnez tout, et cliquez sur Télécharger maintenant et installer après redémarrage.
- Astuce : Effectuez toujours une sauvegarde de votre répertoire JENKINS_HOME avant une mise à jour majeure de plugin ou un changement.
Rétrograder un plugin : Si un conflit est apparu immédiatement après la mise à jour d'un plugin spécifique, essayez de le rétrograder vers sa version de travail précédente. Cela nécessite un processus manuel :
1. Allez sur le centre de mise à jour Jenkins : https://updates.jenkins-ci.org/download/plugins/<nom-du-plugin>/ (remplacez <nom-du-plugin> par l'ID réel du plugin, par exemple git).
2. Téléchargez le fichier .jpi de la version antérieure souhaitée.
3. Copiez le fichier .jpi dans votre répertoire JENKINS_HOME/plugins, en remplaçant celui existant.
4. Supprimez le fichier .jpi.disabled s'il existe pour ce plugin (cela empêche Jenkins de télécharger à nouveau la version plus récente).
5. Redémarrez Jenkins.
Désactiver/Supprimer les plugins problématiques : Si un plugin spécifique est identifié comme le coupable et n'est pas critique, essayez de le désactiver temporairement. Allez dans Gérer Jenkins -> Gérer les plugins -> onglet Installés, décochez le plugin, et redémarrez Jenkins. Si la stabilité revient, vous avez trouvé votre conflit. Si le plugin est inutile, envisagez de le désinstaller.

2. Techniques avancées de dépannage

Isoler le conflit : Si vous soupçonnez un plugin nouvellement installé ou mis à jour, essayez de désactiver les plugins un par un (ou par petits groupes) et redémarrez Jenkins jusqu'à ce que le problème disparaisse. Cela aide à identifier la cause exacte.
Utiliser le redémarrage sécurisé Jenkins : Si Jenkins ne parvient pas à démarrer ou devient instable immédiatement après un changement de plugin, vous pouvez essayer un "Redémarrage sécurisé". Cela démarre Jenkins avec tous les plugins désactivés, vous permettant d'accéder à la page Gérer les plugins et de résoudre le problème.

Pour effectuer un redémarrage sécurisé :
```
# Si Jenkins fonctionne comme un service (par exemple, systemd)
sudo systemctl stop jenkins
java -Dhudson.model.UpdateCenter.safeMode=true -jar jenkins.war --httpPort=8080 # ou votre port préféré
# Ensuite, une fois le problème résolu via l'interface, redémarrez normalement
sudo systemctl start jenkins
```
Alternativement, vous pouvez désactiver manuellement les plugins en renommant leurs fichiers .jpi en .jpi.disabled dans JENKINS_HOME/plugins avant de démarrer Jenkins.
Examen manuel des dépendances : Pour les problèmes persistants, en particulier ceux impliquant NoClassDefFoundError ou NoSuchMethodError, vous devrez peut-être examiner manuellement les dépendances des plugins. La plupart des plugins ont un fichier META-INF/MANIFEST.MF dans leur .jpi (qui est un fichier ZIP) qui liste leurs dépendances directes. Vous pouvez décompresser le .jpi et inspecter ce fichier. Comparez ces dépendances avec celles d'autres plugins qui pourraient être en conflit.
Vérifier la compatibilité du noyau Jenkins : Vérifiez toujours la matrice de compatibilité de vos plugins sur le site Web Jenkins (plugins.jenkins.io). Chaque plugin liste généralement la version minimale du noyau Jenkins requise. Assurez-vous que votre noyau Jenkins est suffisamment à jour pour tous vos plugins installés.

3. Meilleures pratiques pour la prévention

Prévenir les conflits est toujours mieux que de les résoudre.

Mises à jour régulières et incrémentielles : N'attendez pas trop longtemps entre les mises à jour. Appliquez les mises à jour de plugins régulièrement, mais par petits lots. Cela facilite l'identification de la mise à jour qui a causé un problème.
Environnement de test/staging : N'appliquez jamais de mises à jour majeures de plugins directement sur une instance Jenkins de production. Testez toujours les changements dans un environnement de staging ou de développement dédié qui reflète votre configuration de production.
Sauvegarder JENKINS_HOME régulièrement : Avant tout changement significatif (installations de plugins, mises à jour, mises à niveau du noyau Jenkins), sauvegardez votre répertoire JENKINS_HOME. Cela permet une récupération rapide en cas de problème.
Surveiller activement les logs Jenkins : Mettez en place une surveillance des logs et des alertes pour votre instance Jenkins. Cela peut vous aider à détecter rapidement les nouvelles erreurs liées aux plugins.
Lire les notes de version des plugins : Avant de mettre à jour un plugin, parcourez ses notes de version pour détecter tout problème de compatibilité connu, changement cassant ou nouvelle exigence de dépendance.
Installation minimaliste des plugins : Installez uniquement les plugins dont vous avez vraiment besoin. Chaque plugin supplémentaire augmente la surface potentielle de conflits et alourdit la charge de maintenance.
Comprendre les interdépendances des plugins : Certains plugins sont conçus pour fonctionner ensemble (par exemple, Pipeline et divers outils SCM/build). Soyez conscient de ces relations. Par exemple, si vous utilisez Jenkins Pipeline, assurez-vous que vos plugins Workflow sont compatibles.
Utiliser JENKINS_HOME/.jenkins-plugins.yaml (Avancé) : Pour les environnements hautement contrôlés, vous pouvez gérer votre liste de plugins de manière déclarative. Ce fichier spécifie les versions exactes des plugins, garantissant la cohérence. Bien que cela n'empêche pas tous les conflits, cela garantit que vous déployez toujours un ensemble connu de versions de plugins.
```
plugins:
  - git:4.11.5
  - pipeline-stage-view:2.27
  - workflow-aggregator:2.6
```
Remarque : Ce fichier est généralement utilisé lors de la configuration d'instances Jenkins via des outils comme JCasC ou lors de la gestion de plugins pour des environnements reproductibles.

Guide de dépannage étape par étape

Suivez ces étapes lorsque vous rencontrez un conflit de plugin suspecté :

Sauvegarder JENKINS_HOME : Première étape cruciale.
Vérifier les changements récents : Quelle a été la dernière chose que vous avez installée ou mise à jour (plugin, noyau Jenkins, correctif OS) ? C'est souvent le coupable.
Inspecter les logs Jenkins : Recherchez les messages ERROR, WARNING, SEVERE, et surtout les traces de pile pour NoClassDefFoundError, NoSuchMethodError, LinkageError. Notez les noms exacts des plugins mentionnés.
Essayer un redémarrage sécurisé : Si Jenkins est instable ou ne démarre pas, utilisez java -Dhudson.model.UpdateCenter.safeMode=true -jar jenkins.war pour accéder à l'interface.
Désactiver les plugins suspects : Depuis Gérer Jenkins -> Gérer les plugins -> Installés, désactivez le(s) plugin(s) identifié(s) dans les logs ou ceux modifiés le plus récemment. Redémarrez Jenkins.
- Si le problème se résout, vous avez trouvé votre plugin conflictuel. Procédez à l'investigation d'alternatives, de versions plus anciennes, ou signalez le problème aux mainteneurs du plugin.
Mettre à jour tous les plugins (si sûr de le faire) : Si l'étape 5 n'a pas aidé et que Jenkins est suffisamment stable, essayez de mettre à jour tous les plugins. Redémarrez Jenkins.
Rétrograder les plugins problématiques : Si une mise à jour a causé le problème, rétrogradez le plugin spécifique en utilisant la méthode manuelle de remplacement du .jpi.
Consulter la documentation et la communauté du plugin : Vérifiez les pages officielles des plugins sur plugins.jenkins.io pour les problèmes connus, les notes de compatibilité et les forums communautaires.
Retour arrière systématique : Si tout le reste échoue et que vous avez une sauvegarde de JENKINS_HOME datant d'avant le début du problème, restaurez-la. Ensuite, réintroduisez les changements de manière incrémentielle, en testant après chacun.

Que faire la prochaine fois

Les conflits de plugins Jenkins sont plus faciles à gérer lorsque vous gardez un petit ensemble de plugins, enregistrez les versions exactes, testez les mises à jour loin de la production et lisez la première trace de pile significative au lieu de deviner à partir du dernier écran d'échec.

Traiter les changements de plugins comme des changements de production

Les mises à jour de plugins semblent petites car le bouton se trouve dans l'interface Jenkins. Elles ne sont pas petites. Une mise à jour de plugin peut modifier les étapes de pipeline, les dépendances transitives, la gestion des identifiants, les formulaires d'interface, le comportement de sérialisation ou les exigences minimales du noyau Jenkins. Dans une instance Jenkins occupée, c'est une gestion de changement de production.

Avant de toucher aux plugins, capturez l'état actuel. Au minimum, sauvegardez la version de Jenkins, la liste des plugins avec leurs versions, et une sauvegarde ou un instantané de JENKINS_HOME. Si Jenkins fonctionne dans un conteneur, sauvegardez également l'étiquette de l'image et les arguments de démarrage. Lorsqu'un retour arrière est nécessaire, un vague souvenir ne suffit pas.

Vous pouvez exporter la liste des plugins installés depuis la console de script ou la CLI, mais utilisez la méthode déjà standard dans votre environnement. L'important est que la liste inclue les versions exactes. "Dernier plugin git" n'est pas un plan de retour arrière.

Trouver le plugin nommé par la trace de pile

Une trace de pile Java contient souvent plusieurs noms de plugins. Ne supposez pas que le premier nom est le coupable. Recherchez la première exception au niveau de l'application et les classes autour d'elle. Un NoSuchMethodError peut mentionner une classe d'un plugin de bibliothèque, tandis que le plugin qui a appelé la méthode manquante apparaît quelques lignes plus haut.

Par exemple, si une étape de pipeline échoue après une mise à jour et que la trace de pile contient à la fois workflow-step-api et un plugin de fournisseur cloud, le plugin de fournisseur cloud peut utiliser une version d'API qui ne correspond plus à l'ensemble des plugins de workflow installés. Mettre à jour un seul plugin peut laisser la famille de pipeline désynchronisée.

Les pages des plugins Jenkins listent généralement les dépendances et les versions requises du noyau. Utilisez ces pages pour confirmer la compatibilité plutôt que de deviner. Si un plugin nécessite un noyau Jenkins plus récent que celui que vous utilisez, mettre à niveau uniquement le plugin n'est pas une solution valide.

Ne pas tout mettre à jour aveuglément sur un contrôleur cassé

Mettre à jour tous les plugins peut résoudre une inadéquation de dépendances, mais cela peut aussi aggraver un petit incident. Si Jenkins s'est cassé juste après un changement de plugin, commencez par ce changement. Revenez en arrière ou désactivez-le si possible. Une fois le contrôleur stable, planifiez une mise à jour plus large dans une fenêtre de maintenance.

Tout mettre à jour est plus raisonnable lorsque l'instance est très en retard, que de nombreux plugins affichent des avertissements de dépendance et que vous disposez d'une sauvegarde testée. Même dans ce cas, mettez à jour d'abord dans un clone ou un contrôleur de staging. Exécutez des jobs représentatifs, en particulier les jobs qui utilisent des identifiants, l'extraction SCM, Docker, les agents Kubernetes, les bibliothèques partagées et les plugins de déploiement.

Les plugins les plus risqués sont généralement ceux qui participent à presque chaque build : Pipeline, Git, Credentials, SCM API, Script Security, Docker, Kubernetes, Matrix Authorization et les plugins de configuration en tant que code. Traitez-les comme des composants de plateforme partagés.

Mode sans échec et désactivation manuelle

Si Jenkins ne démarre pas, le mode sans échec peut vous donner un moyen de revenir à l'interface avec les plugins désactivés. Si cela n'est pas disponible dans votre packaging, la désactivation manuelle est toujours possible en créant des fichiers marqueurs .disabled ou en renommant les fichiers de plugins dans JENKINS_HOME/plugins, selon votre version de Jenkins et son comportement de démarrage.

Faites un changement à la fois et prenez des notes. Si vous désactivez dix plugins à la fois et que Jenkins démarre, vous en savez moins que vous ne le pensez. Commencez par le plugin le plus étroitement lié à l'échec. Si Jenkins ne peut pas se charger à cause d'un plugin de dépendance, rappelez-vous que le désactiver peut également désactiver tous les plugins qui en dépendent.

Après des changements manuels, inspectez à la fois l'interface et les logs. Jenkins peut démarrer mais laisser les plugins dépendants en échec. Une page de connexion verte ne signifie pas que le graphe des plugins est sain.

Les bibliothèques partagées peuvent ressembler à des conflits de plugins

Toutes les erreurs après une mise à jour de plugin ne sont pas des bugs de plugin. Les bibliothèques partagées encapsulent souvent les étapes de plugin. Si un plugin modifie un paramètre d'étape, un type de retour ou une règle de validation, l'erreur peut pointer vers votre code de bibliothèque partagée. C'est toujours un problème de compatibilité, mais la correction peut se trouver dans la bibliothèque plutôt que dans la version du plugin.

Vérifiez si les jobs simples utilisant directement le plugin fonctionnent toujours. Si l'utilisation directe fonctionne et que seuls les jobs basés sur la bibliothèque échouent, inspectez la bibliothèque. Si les deux échouent, concentrez-vous sur le plugin, la dépendance ou le noyau Jenkins.

Garder l'ensemble des plugins ennuyeux

Les contrôleurs Jenkins les plus stables que j'ai vus ont moins de plugins que ce que les gens attendent. Ils n'installent pas un plugin pour chaque petite commodité. Ils préfèrent les plugins maintenus avec une propriété claire, des versions récentes et une large utilisation. Ils suppriment les plugins inutilisés après avoir confirmé qu'aucun job n'en dépend.

Auditez les plugins quelques fois par an. Recherchez les plugins désactivés, les plugins abandonnés, les plugins installés pour un seul ancien job et les plugins qui se chevauchent résolvant le même problème. Chaque plugin installé ajoute du code à charger, des dépendances à résoudre, des avis de sécurité à suivre et des chemins de mise à niveau à tester.

Si vous utilisez Jenkins Configuration as Code ou un déploiement Jenkins basé sur une image, épinglez délibérément les versions des plugins. Flotter vers la dernière version à chaque build rend les retours arrière difficiles et peut introduire des changements alors que personne n'a planifié de maintenance.