CLI vs. Groovy : Choisir le bon outil pour les tâches Jenkins à distance

Jenkins vous offre plusieurs façons d'exécuter des tâches administratives à distance. En ce qui concerne l'exécution de commandes à distance, deux méthodes principales se démarquent : l'interface en ligne de commande (CLI) de Jenkins et la console de scripts Groovy. Les deux servent à automatiser et gérer Jenkins, mais ils répondent à des cas d'utilisation différents et possèdent des capacités et des limitations distinctes. Comprendre quand utiliser chaque outil est crucial pour une gestion efficace des pipelines CI/CD et l'administration de Jenkins.

Le choix pratique est généralement simple : utilisez Jenkins CLI pour les opérations limitées sur les jobs et le contrôleur, et utilisez Groovy uniquement lorsque vous avez besoin d'un accès à l'API Jenkins que la CLI n'expose pas.

Interface en ligne de commande Jenkins (CLI)

La CLI Jenkins est un outil puissant qui vous permet d'interagir avec votre instance Jenkins depuis la ligne de commande. Elle est particulièrement utile pour scripter des tâches rapides, vérifier l'état des jobs, déclencher des builds et effectuer des opérations administratives de base. Le client CLI est généralement téléchargé sous forme de fichier .jar et exécuté via Java.

Capacités et cas d'utilisation

Opérations simples et atomiques : Idéal pour exécuter des commandes uniques et simples comme lister les jobs, builder un job spécifique ou récupérer les logs de build.
Script de déclenchement de builds : Intégrez facilement les builds Jenkins dans des scripts externes ou d'autres outils d'automatisation.
Vérifications d'état : Interrogez rapidement l'état des contrôleurs, agents ou jobs Jenkins.
Administration : Effectuez des tâches administratives de base comme la gestion des plugins ou la reconfiguration de Jenkins.
Intégration : S'intègre parfaitement avec les scripts shell, les tâches cron et autres automatisations en ligne de commande.

Limitations

Complexité limitée : Ne convient pas pour des logiques complexes, des exécutions conditionnelles ou des workflows complexes nécessitant une gestion d'état.
Pas d'état persistant : Chaque commande CLI est une exécution indépendante ; elle ne maintient pas de contexte ou d'état entre plusieurs appels.
Courbe d'apprentissage plus raide pour les tâches complexes : Bien que les commandes simples soient intuitives, la construction de séquences d'automatisation complexes uniquement avec des commandes CLI peut devenir fastidieuse.

Premiers pas avec Jenkins CLI

Téléchargez le client CLI : Vous pouvez télécharger le fichier jenkins-cli.jar depuis votre instance Jenkins à l'adresse http://<JENKINS_URL>/jnlpJars/jenkins-cli.jar.
Authentification : Vous devez authentifier vos requêtes CLI. Cela peut être fait en utilisant des jetons API ou des identifiants nom d'utilisateur/mot de passe.
Exécutez des commandes : Utilisez Java pour exécuter le fichier .jar avec les commandes et arguments appropriés.

Exemple : Lister tous les jobs Jenkins

java -jar jenkins-cli.jar -s http://<JENKINS_URL>/ -auth <USERNAME>:<API_TOKEN> list-jobs

Exemple : Déclencher un build pour un job spécifique

java -jar jenkins-cli.jar -s http://<JENKINS_URL>/ -auth <USERNAME>:<API_TOKEN> build <JOB_NAME>

Exemple : Obtenir la sortie console du dernier build

java -jar jenkins-cli.jar -s http://<JENKINS_URL>/ -auth <USERNAME>:<API_TOKEN> console <JOB_NAME>

Console de scripts Groovy

La console de scripts Groovy Jenkins (souvent appelée Script Console ou Groovy Console) fournit un environnement interactif puissant pour exécuter des scripts Groovy arbitraires directement sur le contrôleur Jenkins. Cela vous donne accès à l'API Java interne de Jenkins, permettant une automatisation, une administration et même un développement de fonctionnalités personnalisées hautement sophistiqués et dynamiques.

Capacités et cas d'utilisation

Logiques et workflows complexes : Exécutez des scripts complexes avec une logique conditionnelle, des boucles et un traitement de données personnalisé.
Accès direct à l'API : Interagissez directement avec les objets Java et les API de base de Jenkins pour un contrôle fin.
Manipulation de données : Interrogez les données Jenkins, modifiez les configurations et générez des rapports personnalisés.
Administration système : Effectuez des tâches administratives avancées, résolvez des problèmes et automatisez des procédures de configuration complexes.
Développement et test de plugins : Utile pour tester les fonctionnalités des plugins ou même en développer de nouveaux.

Limitations

Problèmes de sécurité : L'exécution de scripts arbitraires sur le contrôleur Jenkins peut présenter des risques de sécurité importants s'ils ne sont pas gérés avec soin. Les scripts doivent être soigneusement examinés et testés.
Consommation de ressources du contrôleur : Des scripts lourds ou inefficaces peuvent consommer des ressources importantes du contrôleur, impactant potentiellement les performances de Jenkins.
L'exécution à distance nécessite de la prudence : Vous pouvez exécuter Groovy à distance via les commandes Jenkins CLI groovy ou groovysh lorsque cela est autorisé, mais cela exécute toujours un code puissant sur le contrôleur.
Nécessite des connaissances en Groovy/Java : Exige une solide compréhension de Groovy et des API internes de Jenkins.

Premiers pas avec la console de scripts Groovy

Accédez à la console : Naviguez vers http://<JENKINS_URL>/script dans votre navigateur.
Écrivez des scripts : Tapez ou collez votre script Groovy dans la zone de texte fournie.
Exécutez : Cliquez sur le bouton "Run".
Visualisez les résultats : La sortie de votre script sera affichée sous l'éditeur.

Exemple : Obtenir une liste de tous les jobs et leur statut du dernier build

Jenkins.instance.getAllItems(Job.class).each {
    job -> println "Job: ${job.name}, Dernier statut du build: ${job.lastBuild?.result ?: 'Aucun build pour le moment'}"
}

Exemple : Mettre à jour la description d'un job

def jobName = "NomDeVotreJob"
def newDescription = "Ceci est une description automatisée."
def job = Jenkins.instance.getItemByFullName(jobName)

if (job) {
    job.setDescription(newDescription)
    job.save()
    println "Description mise à jour avec succès pour le job : ${jobName}"
} else {
    println "Job '${jobName}' non trouvé."
}

Exemple : Désactiver un job

def jobName = "JobADesactiver"
def job = Jenkins.instance.getItemByFullName(jobName)

if (job instanceof hudson.model.Job) {
    job.setDisabled(true)
    job.save()
    println "Le job '${jobName}' a été désactivé."
} else {
    println "Job '${jobName}' non trouvé ou n'est pas un type de job."
}

CLI vs. Groovy : Quand utiliser quoi

Le choix entre la CLI Jenkins et la console de scripts Groovy dépend en grande partie de la complexité, de la portée et de la nature de la tâche à effectuer.

Utilisez la CLI Jenkins lorsque :

Vous devez effectuer des actions rapides et uniques depuis votre machine locale ou un script.
Votre tâche implique le déclenchement de builds, la vérification de l'état des jobs ou la récupération d'informations de base.
Vous intégrez des opérations Jenkins dans des scripts shell externes ou des outils CI/CD qui attendent des arguments en ligne de commande.
Vous souhaitez éviter d'exécuter du code complexe directement sur le contrôleur Jenkins pour des raisons de sécurité ou de ressources.
Vous devez effectuer des tâches administratives de base qui sont directement exposées en tant que commandes CLI.

Utilisez la console de scripts Groovy lorsque :

Vous devez implémenter des workflows d'automatisation complexes avec prise de décision et logique personnalisée.
Vous avez besoin d'un accès direct aux API internes de Jenkins pour manipuler les configurations, interroger les données en détail ou gérer les paramètres système.
Vous effectuez une administration avancée, un dépannage ou une analyse de données qui dépasse les simples commandes CLI.
Vous devez interagir avec des objets ou plugins Jenkins spécifiques d'une manière non directement prise en charge par la CLI.
Vous êtes à l'aise avec les scripts Groovy et comprenez les implications de sécurité de l'exécution de code sur le contrôleur.

Bonnes pratiques et considérations

Pour la CLI Jenkins :

Authentification sécurisée : Utilisez toujours des jetons API pour l'authentification plutôt que votre mot de passe. Stockez les jetons en toute sécurité.
Paramétrage : Rendez vos scripts CLI robustes en paramétrant les URLs, les identifiants et les noms de jobs.
Gestion des erreurs : Implémentez des vérifications de succès/échec d'exécution des commandes dans vos scripts appelants.

Pour la console de scripts Groovy :

Sécurité avant tout : Ne jamais exécuter de scripts non fiables. Examinez attentivement tout script avant exécution. Envisagez de restreindre l'accès à la console de scripts.
Testez minutieusement : Testez toujours vos scripts d'abord dans un environnement non productif.
Gestion des ressources : Soyez conscient de l'impact sur les performances de vos scripts sur le contrôleur Jenkins. Évitez les opérations longues et gourmandes en ressources directement dans la console sans optimisation appropriée ou exécution en arrière-plan.
Utilisez un accès API pris en charge : Dans le code Jenkins actuel, préférez Jenkins.get() de jenkins.model.Jenkins lors de l'écriture de Groovy réutilisable. De nombreux extraits plus anciens utilisent encore Jenkins.instance ; vérifiez votre version de Jenkins et vos imports.

À retenir

Utilisez la CLI Jenkins lorsque la tâche correspond à une commande existante, comme builder un job, lister les jobs ou lire la sortie console. Utilisez Groovy lorsque vous avez besoin de modifications directes au niveau des objets dans Jenkins, et traitez chaque script comme un code administratif au niveau du contrôleur. Testez Groovy d'abord dans un contrôleur non productif, gardez les scripts petits et enregistrez la version finale dans le contrôle de source.