Maîtriser la Console de Script Groovy de Jenkins pour l'Administration Système Avancée

Jenkins est l'épine dorsale des pipelines CI/CD modernes, offrant une flexibilité inégalée grâce à son modèle d'extensibilité. Alors que la plupart des administrateurs s'appuient sur l'interface utilisateur graphique (GUI) ou les scripts de pipeline déclaratifs, la Console de Script Jenkins—alimentée par Groovy—offre une interface directe et de bas niveau pour l'introspection immédiate du système, les modifications de configuration et l'automatisation avancée qui va au-delà des étapes de pipeline standard. Cette console est indispensable aux administrateurs système qui ont besoin de dépanner des problèmes de production, d'effectuer des mises à jour en masse ou de gérer directement le système central de Jenkins.

Ce guide vous expliquera comment tirer parti de la Console de Script Groovy pour exécuter de puissantes tâches administratives, transformant des interventions manuelles complexes en opérations efficaces et scriptables. La maîtrise de cet outil est essentielle pour passer de la gestion standard des pipelines à une véritable administration système de Jenkins.

Comprendre la Console de Script Jenkins

La Console de Script Jenkins (Gérer Jenkins -> Console de Script) fournit une passerelle directe pour interagir avec le modèle d'objet du contrôleur (master) Jenkins en cours d'exécution en utilisant Groovy, le langage de script préféré de Jenkins. Elle permet aux administrateurs d'accéder à presque tous les objets au sein de l'environnement d'exécution de Jenkins, y compris les configurations système, les objets de tâche (job), les enregistrements de build et les agents connectés.

Pourquoi utiliser la Console de Script ?

Exécution Immédiate: Exécutez des scripts instantanément sans attendre le déclenchement d'une tâche ou le démarrage d'un pipeline.
Débogage du Système: Accédez à l'état interne, aux journaux et aux détails de configuration qui ne sont pas exposés via l'interface graphique (GUI).
Opérations en Masse: Modifiez plusieurs tâches, reconfigurez des agents ou supprimez rapidement d'anciennes données sur l'ensemble de l'instance.
Scripts Prototypes: Testez la logique Groovy avant de l'intégrer dans des bibliothèques partagées ou des pipelines déclaratifs.

Précaution de Sécurité : La Puissance de l'Accès Direct

AVERTISSEMENT : Les scripts exécutés dans la console s'exécutent avec des privilèges d'administration complets sur le contrôleur Jenkins. Un script mal écrit peut corrompre des configurations, supprimer des builds ou faire planter l'instance Jenkins. Testez toujours les scripts complexes de manière approfondie dans un environnement de non-production au préalable.

Objets Groovy Essentiels et Accès API

La puissance de la console réside dans l'accès direct aux objets Jenkins centraux. Ces objets sont implicitement disponibles dans l'environnement d'exécution Groovy :

Jenkins.instance: L'objet singleton central de Jenkins, représentant le contrôleur en cours d'exécution.
Hudson: Un alias pour Jenkins.
Jenkins.instance.getItemByFullName('JobName'): Accède à une tâche (job) spécifique.
Jenkins.instance.getComputer('AgentName'): Accède à un agent (nœud) spécifique.

Accéder à l'Instance Jenkins

Pour vérifier que vous y avez accès, la commande la plus simple consiste à afficher la version de Jenkins :

println "Jenkins Version: ${Jenkins.instance.version}"
println "Running as user: ${Jenkins.instance.getAuthentication().getName()}"

Scripts Administratifs Pratiques

Voici plusieurs scripts exploitables qui démontrent un contrôle administratif avancé via la Console de Script.

1. Mise à Jour des Configurations de Tâches en Masse

Ce script itère sur toutes les tâches existantes et modifie un élément de configuration spécifique, comme le changement d'une description ou la mise à jour de l'URL SCM pour plusieurs projets simultanément. Cet exemple ajoute un suffixe standardisé à la description de tous les projets Freestyle.

import hudson.model.FreeStyleProject

final String SUFFIX = " [Automated Update]"

def count = 0

Jenkins.instance.getAllItems(FreeStyleProject.class).each { job ->
    if (!job.getDescription().endsWith(SUFFIX)) {
        job.setDescription(job.getDescription() + SUFFIX)
        job.save()
        println "Updated description for: ${job.getName()}"
        count++
    }
}
println "\nFinished. Total jobs updated: ${count}"

2. Gérer les Agents Jenkins (Nœuds)

Les administrateurs doivent souvent mettre des agents hors ligne pour la maintenance ou déconnecter manuellement des nœuds défectueux.

Déconnecter Temporairement un Agent

Ce script déconnecte un agent, empêchant le démarrage de nouvelles builds sur celui-ci, mais permettant aux builds en cours de se terminer.

import hudson.model.Computer

final String AGENT_NAME = "my-specific-agent"

def agent = Computer.instance.get(AGENT_NAME)

if (agent) {
    // Set temporarily offline
    agent.setTemporarilyOffline(true, "Maintenance started by Admin Script.")
    println "Agent '${AGENT_NAME}' set to temporarily offline."
} else {
    println "Agent '${AGENT_NAME}' not found."
}

Forcer un Agent Hors Ligne et Déconnecter les Tâches en Cours

Si un agent doit être immédiatement mis hors service, vous pouvez le forcer hors ligne et déconnecter toute build en cours d'exécution, ce qui les marquera comme ayant échoué ou ayant été annulées selon la configuration.

import hudson.model.Computer

final String AGENT_NAME = "unresponsive-node-01"

def agent = Computer.instance.get(AGENT_NAME)

if (agent) {
    // Force offline and disconnect running tasks immediately
    agent.doDoDisconnect()
    println "Agent '${AGENT_NAME}' forcefully disconnected."
} else {
    println "Agent '${AGENT_NAME}' not found."
}

3. Manipulation des Builds en Cours

Lorsqu'une build critique reste bloquée ou nécessite une annulation immédiate, la Console de Script offre le chemin le plus rapide.

Annuler une Build Spécifique en Cours d'Exécution

Pour annuler une build identifiée par son chemin complet (par exemple, PipelineJob/BuildNumber) :

// Example: Aborting build #5 of the job named 'CriticalDeploy'
final String JOB_NAME = "CriticalDeploy"
final int BUILD_NUMBER = 5

def job = Jenkins.instance.getItemByFullName(JOB_NAME)

def build = job.getBuild(BUILD_NUMBER)

if (build && build.isBuilding()) {
    build.doCancel()
    println "Build ${JOB_NAME}#${BUILD_NUMBER} has been cancelled."
} else {
    println "Build ${JOB_NAME}#${BUILD_NUMBER} is not running or does not exist."
}

4. Nettoyage des Anciens Enregistrements de Build

La gestion de l'espace disque nécessite souvent de supprimer agressivement les anciennes builds. Ce script identifie et supprime toutes les builds de plus de 30 jours pour une tâche spécifiée.

import hudson.model.Job
import java.util.concurrent.TimeUnit

final String TARGET_JOB = "LegacyArchivingJob"
final int DAYS_TO_KEEP = 30

def job = Jenkins.instance.getItemByFullName(TARGET_JOB)

if (job instanceof Job) {
    long cutoffTime = System.currentTimeMillis() - TimeUnit.DAYS.toMillis(DAYS_TO_KEEP)
    int deletedCount = 0

    job.getBuilds().each { build ->
        if (build.getTimeInMillis() < cutoffTime) {
            println "Deleting old build: ${build.getDisplayName()}"
            build.delete()
            deletedCount++
        }
    }
    println "\nCleanup complete. Deleted ${deletedCount} builds for ${TARGET_JOB}."
} else {
    println "Job '${TARGET_JOB}' not found or is not a standard Job type."
}

Meilleures Pratiques pour le Scripting de Console

Lorsque vous effectuez des modifications au niveau du système, respectez ces meilleures pratiques pour maintenir la stabilité :

Utilisez .save(): Chaque fois que vous modifiez un objet de configuration (comme une Tâche ou une Vue), vous devez appeler .save() sur cet objet pour que la modification persiste après le redémarrage de Jenkins. Les configurations ne sont conservées en mémoire que jusqu'à ce qu'elles soient sauvegardées.
Vérifiez l'Existence de l'Objet : Enveloppez toujours les appels d'API avec des vérifications (if (object) ou try-catch) pour éviter que la console ne plante si vous faites une erreur de frappe sur le nom d'une tâche ou d'un agent.
Évitez les Boucles Persistantes : Les scripts s'exécutent de manière synchrone. N'exécutez pas de boucles ou de processus de longue durée directement dans la console, sauf si vous êtes certain qu'ils se termineront rapidement, car cela bloque l'interface utilisateur de la console.
Tirez Parti des Méthodes Intégrées : Les objets Groovy de Jenkins ont souvent des méthodes d'assistance spécifiques (comme doCancel() ou doDoDisconnect()). Utilisez-les au lieu d'essayer de manipuler manuellement l'état interne lorsque cela est possible.
Utilisez le Mode Silencieux (si applicable) : Lorsque vous effectuez des opérations en masse qui génèrent des mises à jour excessives du statut de build, déterminez s'il est justifié de désactiver temporairement les fonctionnalités de notification d'événements, bien que cela nécessite généralement un accès système plus approfondi que l'administration standard.

Maîtriser la Console de Script Groovy de Jenkins vous fait passer du simple utilisateur de Jenkins à l'administrateur actif et l'optimisateur de son cœur. En pratiquant ces techniques, vous obtenez un contrôle granulaire sur votre serveur d'automatisation, améliorant considérablement la réactivité lors de fenêtres de maintenance complexes ou d'urgences.