Hub de Connaissances DevOps
Hub de Connaissances DevOps

Dépannage rapide des builds échoués avec la CLI Jenkins

Diagnostiquez et résolvez rapidement les échecs de builds Jenkins grâce à ce guide complet sur la CLI Jenkins. Apprenez à récupérer des logs de console détaillés, à filtrer les erreurs à l'aide de `grep`, à inspecter les variables d'environnement de build via de puissants scripts Groovy, et à relancer efficacement les builds. Cet article vous fournit les commandes pratiques et les meilleures pratiques pour minimiser les temps d'arrêt, rendant le dépannage de votre CI/CD plus rapide et plus efficace que jamais.

45 vues

Dépannage rapide des échecs de construction avec l'interface CLI de Jenkins

Jenkins est l'épine dorsale des pipelines d'intégration continue et de livraison continue (CI/CD) pour d'innombrables organisations. Bien qu'il automatise les processus de construction, de test et de déploiement, les échecs de construction font inévitablement partie du développement logiciel. Lorsqu'une construction échoue, un diagnostic et une résolution rapides sont essentiels pour minimiser les temps d'arrêt et maintenir l'avancement du développement.

Bien que l'interface utilisateur Web de Jenkins fournisse des informations exhaustives, le moyen le plus rapide de dépanner est parfois directement via l'interface de ligne de commande (CLI) de Jenkins. La CLI offre une alternative puissante, scriptable et souvent plus rapide à la navigation dans l'interface utilisateur, en particulier pour les tâches répétitives ou lors du traitement de nombreux journaux de construction.

Ce guide vous expliquera comment exploiter la CLI de Jenkins pour diagnostiquer rapidement les échecs de construction, récupérer les journaux détaillés, inspecter les variables d'environnement et redémarrer efficacement les constructions.

Pourquoi utiliser la CLI de Jenkins pour le dépannage ?

La CLI de Jenkins offre plusieurs avantages pour le dépannage :

  • Vitesse : Récupérez rapidement les journaux et les informations sans navigation par navigateur.
  • Automatisation : Intégrez les étapes de dépannage dans des scripts ou des rapports automatisés.
  • Accès à distance : Effectuez des diagnostics depuis n'importe quel terminal ayant un accès réseau à votre instance Jenkins.
  • Efficacité : Filtrez les journaux et les informations à l'aide d'outils shell standard tels que grep, awk et sed.

Prérequis

Avant de pouvoir commencer le dépannage avec la CLI de Jenkins, assurez-vous d'avoir ce qui suit :

  1. Serveur Jenkins en cours d'exécution : Une instance Jenkins active à laquelle vous avez un accès administratif.
  2. JAR de la CLI Jenkins : Téléchargez le fichier jenkins-cli.jar à partir de votre instance Jenkins. Vous pouvez généralement le trouver à l'adresse JENKINS_URL/jnlpJars/jenkins-cli.jar.
  3. Authentification : La CLI nécessite une authentification. La méthode recommandée consiste à utiliser un jeton API pour un utilisateur Jenkins. Générez un jeton API via Nom_Utilisateur -> Configure -> Ajouter un nouveau jeton.

Configuration de la CLI

Tout d'abord, téléchargez le jenkins-cli.jar :

wget JENKINS_URL/jnlpJars/jenkins-cli.jar
# Ou en utilisant curl
curl -O JENKINS_URL/jnlpJars/jenkins-cli.jar

Pour simplifier les commandes, vous pouvez définir des variables d'environnement pour votre URL Jenkins, votre nom d'utilisateur et votre jeton API :

export JENKINS_URL="http://your-jenkins-instance.com"
export JENKINS_USER="your_username"
export JENKINS_API_TOKEN="your_api_token"

# Aliassez la commande CLI pour plus de commodité
alias jcli='java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN"'

Maintenant, vous pouvez simplement utiliser jcli suivi de la commande.

Identification des constructions ayant échoué

La première étape du dépannage consiste à identifier quelle tâche et quelle construction ont échoué. Bien que la CLI ne dispose pas d'une commande directe pour lister uniquement les constructions ayant échoué, vous pouvez lister les tâches, puis les inspecter, ou utiliser Groovy pour un filtrage plus avancé.

Liste des tâches

Pour voir une liste de toutes les tâches sur votre instance Jenkins :

jcli list-jobs

Ceci fournit une liste de base. Pour obtenir des informations plus détaillées sur une tâche spécifique, y compris l'état de sa dernière construction, utilisez get-job :

jcli get-job MyPipelineJob

Le résultat (au format XML par défaut) contiendra des informations telles que lastFailedBuild, lastSuccessfulBuild, etc., que vous pourrez analyser.

Astuce : Utilisation de Groovy pour un filtrage avancé

Pour un filtrage plus avancé, en particulier pour trouver des constructions ayant échoué spécifiques, vous pouvez exécuter des scripts Groovy via la CLI. C'est incroyablement puissant.

jcli groovy =
    'Jenkins.instance.getAllItems(hudson.model.Job.class).each { job ->
        def lastBuild = job.getLastBuild()
        if (lastBuild != null && lastBuild.result == hudson.model.Result.FAILURE) {
            println "Failed Job: ${job.name}, Build: ${lastBuild.number}"
        }
    }'

Récupération des journaux de construction détaillés

L'étape la plus courante et la plus cruciale du dépannage est l'examen des journaux de construction (sortie console). La CLI de Jenkins rend cela simple.

Obtention de la sortie console

Pour récupérer l'intégralité de la sortie console d'une construction spécifique, utilisez la commande console :

jcli console MyPipelineJob 123

Remplacez MyPipelineJob par le nom de votre tâche et 123 par le numéro de construction. Cela déversera le journal entier dans votre terminal.

Filtrage des journaux pour les erreurs

Lorsque les journaux sont volumineux, leur analyse manuelle est inefficace. Exploitez grep pour trouver rapidement les messages d'erreur pertinents, les traces de pile ou les mots-clés.

jcli console MyPipelineJob 123 | grep -iE "error|fail|exception|stacktrace"
  • -i : Ignorer la casse.
  • -E : Utiliser des expressions régulières étendues (permet | pour OU).

Cette commande réduit considérablement la sortie, vous aidant à identifier plus rapidement la cause de l'échec.

Surveillance des constructions en direct

Pour les constructions qui sont toujours en cours d'exécution mais qui semblent bloquées ou échouent lentement, vous pouvez surveiller leur sortie console en temps réel, similaire à tail -f :

jcli console MyPipelineJob LAST_BUILD_NUMBER --follow

Ceci diffusera continuellement les nouvelles entrées de journal au fur et à mesure de leur apparition, jusqu'à ce que la construction se termine ou que vous arrêtiez la commande.

Inspection des variables d'environnement de construction

Les variables d'environnement jouent souvent un rôle essentiel dans l'exécution de la construction, influençant les chemins, les secrets et la configuration. Des variables d'environnement incorrectes ou manquantes peuvent entraîner des échecs de construction. Bien qu'il n'y ait pas de commande CLI directe pour répertorier toutes les variables d'environnement d'une construction passée, vous pouvez les récupérer à l'aide d'un script Groovy exécuté via la CLI.

Assurez-vous d'abord que votre pipeline imprime explicitement les variables d'environnement pertinentes ou que vous avez accès à une étape dumpEnvVars (si vous utilisez le plugin Pipeline Utility Steps). Sinon, vous pouvez utiliser Groovy.

Utilisation de Groovy pour accéder aux variables d'environnement

jcli groovy =
    'def job = Jenkins.instance.getItemByFullName("MyPipelineJob")
    def build = job.getBuildByNumber(123)
    if (build) {
        build.getEnvironment().each { key, value ->
            println "${key}=${value}"
        }
    } else {
        println "Build 123 not found for MyPipelineJob"
    }'

Ce script se connecte à l'API Jenkins, récupère la tâche et la construction spécifiées, puis itère et imprime toutes les variables d'environnement qui ont été définies pendant l'exécution de cette construction.

  • Avertissement de sécurité : Soyez prudent lorsque vous imprimez des variables d'environnement, car elles peuvent contenir des informations sensibles (clés API, mots de passe, etc.). Ne le faites que dans des environnements sécurisés et assurez-vous d'un contrôle d'accès approprié.

Analyse des échecs spécifiques aux étapes dans les pipelines

Pour les pipelines Jenkins, savoir quelle étape a échoué est crucial. Bien que la sortie console brute affiche les marqueurs [Pipeline] stage, qui aident à délimiter les étapes, la CLI elle-même ne fournit pas de manière structurée pour interroger directement l'état de l'étape comme le fait l'interface utilisateur (par exemple, Blue Ocean).

Localisation des échecs d'étape dans les journaux

Lors de l'examen de la sortie console, recherchez la dernière entrée [Pipeline] stage avant le message d'erreur ou la trace de pile. Cela indique généralement l'étape où l'échec s'est produit.

jcli console MyPipelineJob 123 | less

À l'intérieur de less, vous pouvez rechercher [Pipeline] stage puis faire défiler pour trouver l'erreur.

Réexécution ou redémarrage des constructions ayant échoué

Une fois que vous avez identifié la cause première d'un échec et appliqué une correction (par exemple, poussé de nouveau code, mis à jour une configuration), vous voudrez réexécuter la construction. La CLI offre un moyen simple de le faire.

Réexécuter une construction entière

Pour déclencher une nouvelle construction pour une tâche :

jcli build MyPipelineJob

Si votre tâche accepte des paramètres, vous pouvez les passer en utilisant l'indicateur -p :

jcli build MyPipelineJob -p BRANCH=feature/fix-bug -p BUILD_VERSION=1.0.1
  • --wait (-s) : Attendre que la construction soit terminée.
  • --verbose (-v) : Afficher la progression et les journaux de construction.
jcli build MyPipelineJob -p BRANCH=master --wait --verbose

Redémarrage à partir d'une étape spécifique (Avancé)

La CLI de Jenkins n'a pas de commande directe restart-stage. Le redémarrage d'un pipeline à partir d'une étape spécifique est principalement une fonctionnalité de l'interface utilisateur de Jenkins (souvent activée par le plugin "Pipeline Steps") ou nécessite une logique de pipeline spécifique.

Cependant, vous pouvez obtenir un effet similaire en concevant votre pipeline pour accepter des paramètres qui permettent de sauter les étapes initiales. Par exemple :

// Dans votre Jenkinsfile

parameters {
    booleanParam(name: 'SKIP_SETUP_STAGE', defaultValue: false, description: 'Skip the initial setup stage')
}

pipeline {
    agent any
    stages {
        stage('Setup') {
            when {
                expression { !params.SKIP_SETUP_STAGE }
            }
            steps {
                echo 'Running setup...'
                // ... setup steps ...
            }
        }
        stage('Build') {
            steps {
                echo 'Building application...'
                // ... build steps ...
            }
        }
        // ... other stages ...
    }
}

Ensuite, vous pouvez déclencher cette construction paramétrée via CLI pour sauter l'étape "Setup" :

jcli build MyPipelineJob -p SKIP_SETUP_STAGE=true

Cette approche nécessite une réflexion préalable dans la conception de votre Jenkinsfile, mais offre un contrôle puissant sur l'exécution du pipeline via la CLI.

Dépannage avancé avec Groovy (via CLI)

Les commandes groovy et groovy-script vous permettent d'exécuter du code Groovy arbitraire sur le contrôleur Jenkins. Cela fournit un accès inégalé à l'API interne de Jenkins pour une inspection et une manipulation approfondies.

Exemple : Obtention des détails de construction

jcli groovy =
    'def job = Jenkins.instance.getItemByFullName("MyPipelineJob")
    def build = job.getBuildByNumber(123)

    if (build) {
        println "Build #${build.number} for ${job.name}"
        println "Status: ${build.result}"
        println "Duration: ${build.durationString}"
        println "Description: ${build.description ?: "N/A"}"
        println "Causes:"
        build.getCauses().each { cause ->
            println "  - ${cause.shortDescription}"
        }
    } else {
        println "Build 123 not found for MyPipelineJob"
    }'

Ce script récupère des informations complètes sur une construction spécifique, ce qui peut être inestimable pour comprendre pourquoi une construction a échoué, surtout si le journal de console est moins clair.

Exécution de scripts Groovy locaux

Pour des scripts Groovy plus complexes, écrivez-les dans un fichier .groovy et exécutez-le via groovy-script :

# my_troubleshooting_script.groovy

def jobName = System.getenv('JOB_NAME') ?: 'MyPipelineJob'
def buildNumber = System.getenv('BUILD_NUMBER') ? Integer.parseInt(System.getenv('BUILD_NUMBER')) : 123

def job = Jenkins.instance.getItemByFullName(jobName)
def build = job?.getBuildByNumber(buildNumber)

if (build) {
    println "Build details for ${job.name} #${build.number}"
    println "Status: ${build.result}"
    build.getAction(hudson.model.ParametersAction.class)?.getParameters()?.each { p ->
        println "Param: ${p.name} = ${p.value}"
    }
} else {
    println "Job ${jobName} or Build ${buildNumber} not found."
}

Ensuite, exécutez-le :

JOB_NAME=MyPipelineJob BUILD_NUMBER=123 jcli groovy-script my_troubleshooting_script.groovy

Cela permet le contrôle de version de vos outils de dépannage.

Conseils pour un dépannage efficace

  • Soyez précis : Lorsque vous utilisez grep, affinez vos modèles. Recherchez des codes d'erreur spécifiques, des messages uniques ou des horodatages.
  • Le contexte est essentiel : Considérez toujours les lignes de journal environnantes. Les erreurs ont souvent des précurseurs ou des messages de suivi qui fournissent plus de contexte.
  • Structure du pipeline : Concevez vos Jenkinsfiles avec des noms d'étapes clairs et une journalisation détaillée dans les étapes critiques. Cela facilite l'identification des problèmes.
  • Utiliser tee : Lorsque vous exécutez des commandes CLI, vous pouvez acheminer la sortie vers tee pour à la fois l'afficher et l'enregistrer dans un fichier pour une analyse ultérieure.
    bash jcli console MyPipelineJob 123 | tee build_123_log.txt | grep -i error
  • Journaux système Jenkins : N'oubliez pas que Jenkins lui-même a des journaux système (JENKINS_HOME/logs). Parfois, un échec de construction est dû à un problème système Jenkins, et non au code du pipeline. Vous pouvez y accéder via l'interface utilisateur (Manage Jenkins -> System Log) ou directement sur le système de fichiers du serveur Jenkins.

Conclusion

La CLI de Jenkins est un outil indispensable pour les administrateurs comme pour les développeurs, offrant un moyen rapide et puissant d'interagir avec votre instance Jenkins. En maîtrisant les commandes permettant de récupérer les journaux, d'inspecter les variables d'environnement (via Groovy) et de déclencher efficacement les constructions, vous pouvez réduire considérablement le temps passé à diagnostiquer et à résoudre les échecs de construction. Intégrez ces techniques CLI dans votre flux de travail quotidien pour maintenir des pipelines CI/CD hautement performants et fiables.

Continuez à explorer la liste étendue des commandes de la CLI Jenkins (jcli help) et la puissance du scripting Groovy pour débloquer des capacités d'automatisation et de dépannage encore plus avancées.