DevOpsナレッジハブ
DevOpsナレッジハブ

Jenkins CLI を使用したビルド失敗の迅速なトラブルシューティング

Jenkins CLI に関するこの包括的なガイドで、Jenkins ビルドの失敗を迅速に診断し解決します。詳細なコンソールログの取得方法、`grep` を使用したエラーのフィルタリング方法、強力な Groovy スクリプトによるビルド環境変数の検査方法、およびビルドの効率的な再実行方法を学びます。この記事では、ダウンタイムを最小限に抑え、CI/CD のトラブルシューティングをこれまで以上に迅速かつ効果的にするための実用的なコマンドとベストプラクティスを提供します。

47 ビュー

Jenkins CLIを使用して失敗したビルドを迅速にトラブルシューティングする方法

Jenkinsは、数えきれないほどの組織にとって継続的インテグレーションおよび継続的デリバリー（CI/CD）パイプラインの基盤となっています。ビルド、テスト、デプロイのプロセスを自動化しますが、ビルドの失敗はソフトウェア開発において避けられない部分です。ビルドが失敗した場合、ダウンタイムを最小限に抑え、開発を継続するためには、迅速な診断と解決が不可欠です。

JenkinsのWeb UIは広範な情報を提供しますが、時にはJenkinsコマンドラインインターフェース（CLI）を直接使用するのが最も迅速なトラブルシューティング方法です。CLIは、特に繰り返し行うタスクや多数のビルドログを扱う場合に、UIをナビゲートするよりも強力で、スクリプト化可能で、多くの場合より迅速な代替手段を提供します。このガイドでは、Jenkins CLIを活用してビルドの失敗を迅速に診断し、詳細なログを取得し、環境変数を検査し、効率的にビルドを再起動する方法について説明します。

トラブルシューティングにJenkins CLIを使用する理由

Jenkins CLIは、トラブルシューティングのためにいくつかの利点を提供します。

  • スピード: ブラウザのナビゲーションなしで、ログと情報を迅速に取得できます。
  • 自動化: トラブルシューティング手順をスクリプトや自動レポートに統合できます。
  • リモートアクセス: Jenkinsインスタンスへのネットワークアクセスがあれば、どのターミナルからでも診断を実行できます。
  • 効率: grep、awk、sedのような標準的なシェルツールを使用して、ログや情報をフィルタリングできます。

前提条件

Jenkins CLIでのトラブルシューティングを開始する前に、以下を確認してください。

  1. Jenkinsサーバーの稼働: 管理者アクセス権を持つアクティブなJenkinsインスタンス。
  2. Jenkins CLI JAR: jenkins-cli.jarファイルをJenkinsインスタンスからダウンロードします。通常、JENKINS_URL/jnlpJars/jenkins-cli.jarで見つけることができます。
  3. 認証: CLIには認証が必要です。推奨される方法は、JenkinsユーザーのAPIトークンを使用することです。APIトークンはYour_User_Name -> Configure -> Add new Tokenから生成できます。

CLIのセットアップ

まず、jenkins-cli.jarをダウンロードします。

wget JENKINS_URL/jnlpJars/jenkins-cli.jar
# またはcurlを使用
curl -O JENKINS_URL/jnlpJars/jenkins-cli.jar

コマンドを簡素化するために、Jenkins URL、ユーザー名、APIトークンの環境変数を設定できます。

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

# CLIコマンドを便宜のためにエイリアス設定
alias jcli='java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN"'

これで、jcliの後にコマンドを続けるだけで使用できます。

失敗したビルドの特定

トラブルシューティングの最初のステップは、どのジョブとビルドが失敗したかを特定することです。CLIには、失敗したビルドのみを一覧表示する直接的なコマンドはありませんが、ジョブを一覧表示してから検査したり、Groovyを使用してより高度なフィルタリングを行ったりすることができます。

ジョブのリスト表示

Jenkinsインスタンス上のすべてのジョブのリストを表示するには：

jcli list-jobs

これは基本的なリストを提供します。特定のジョブに関するより詳細な情報（最新のビルドステータスを含む）を取得するには、get-jobを使用します。

jcli get-job MyPipelineJob

出力（デフォルトではXML形式）には、lastFailedBuild、lastSuccessfulBuildなどの情報が含まれており、これをパースできます。

ヒント: 高度なフィルタリングにGroovyを使用する

特に特定の失敗したビルドを見つけるためのより高度なフィルタリングには、CLI経由でGroovyスクリプトを実行できます。これは非常に強力です。

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}"
        }
    }'

詳細なビルドログの取得

トラブルシューティングにおいて最も一般的で重要なステップは、ビルドログ（コンソール出力）を確認することです。Jenkins CLIはこれを簡単に行えます。

コンソール出力の取得

特定のビルドの完全なコンソール出力を取得するには、consoleコマンドを使用します。

jcli console MyPipelineJob 123

MyPipelineJobをジョブ名に、123をビルド番号に置き換えてください。これにより、ログ全体がターミナルにダンプされます。

エラーのためのログのフィルタリング

ログが膨大である場合、手動で解析するのは非効率です。grepを活用して、関連するエラーメッセージ、スタックトレース、またはキーワードを迅速に見つけます。

jcli console MyPipelineJob 123 | grep -iE "error|fail|exception|stacktrace"
  • -i: 大文字と小文字を区別しない。
  • -E: 拡張正規表現を使用（ORのための|を許可）。

このコマンドは出力を大幅に絞り込み、失敗の原因をより迅速に特定するのに役立ちます。

ライブビルドの監視

まだ実行中であるにもかかわらず、停止しているように見えたり、ゆっくりと失敗しているビルドの場合、tail -fと同様に、リアルタイムでコンソール出力を監視できます。

jcli console MyPipelineJob LAST_BUILD_NUMBER --follow

これにより、ビルドが完了するか、コマンドを停止するまで、新しいログエントリが継続的にストリームされます。

ビルド環境変数の検査

環境変数はビルドの実行においてしばしば重要な役割を果たし、パス、シークレット、および設定に影響を与えます。不正確または欠落した環境変数はビルドの失敗につながる可能性があります。過去のビルドのすべての環境変数をリスト表示する直接的なCLIコマンドはありませんが、CLI経由で実行されるGroovyスクリプトを使用して取得できます。

まず、パイプラインが関連する環境変数を明示的に出力するか、dumpEnvVarsステップにアクセスできることを確認してください（Pipeline Utility Stepsプラグインを使用している場合）。そうでない場合は、Groovyを使用できます。

Groovyを使用して環境変数にアクセスする

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"
    }'

このスクリプトはJenkins APIに接続し、指定されたジョブとビルドを取得し、そのビルドの実行中に設定されたすべての環境変数を反復処理して出力します。

  • セキュリティ警告: 環境変数を出力する際は注意してください。APIキー、パスワードなどの機密情報が含まれる場合があります。安全な環境でのみこれを行い、適切なアクセス制御を確保してください。

パイプラインにおけるステージ固有の失敗の分析

Jenkinsパイプラインの場合、どのステージが失敗したかを知ることは非常に重要です。生のconsole出力には[Pipeline] stageマーカーが表示され、ステージの区別には役立ちますが、CLI自体はUI（例：Blue Ocean）のようにステージの状態を直接クエリするための構造化された方法を提供しません。

ログ内のステージ失敗の特定

console出力を確認する際には、エラーメッセージまたはスタックトレースの直前の最後の[Pipeline] stageエントリを探してください。これは通常、失敗が発生したステージを示しています。

jcli console MyPipelineJob 123 | less

less内で[Pipeline] stageを検索し、スクロールしてエラーを見つけることができます。

失敗したビルドの再実行または再起動

失敗の根本原因を特定し、修正を適用した後（例：新しいコードのプッシュ、設定の更新）、ビルドを再実行したくなるでしょう。CLIはこれを簡単に行う方法を提供します。

ビルド全体の再実行

ジョブの新しいビルドをトリガーするには：

jcli build MyPipelineJob

ジョブがパラメータを受け入れる場合、-pフラグを使用してそれらを渡すことができます。

jcli build MyPipelineJob -p BRANCH=feature/fix-bug -p BUILD_VERSION=1.0.1
  • --wait (-s): ビルドの完了を待ちます。
  • --verbose (-v): 進行状況とビルドログを表示します。
jcli build MyPipelineJob -p BRANCH=master --wait --verbose

特定のステージからの再起動（上級）

Jenkins CLIには直接的なrestart-stageコマンドはありません。特定のステージからパイプラインを再起動する機能は、主にJenkins UIの機能（多くの場合「Pipeline Steps」プラグインによって有効化される）であるか、特定のパイプラインロジックが必要です。

ただし、初期ステージをスキップできるパラメータを受け入れるようにパイプラインを設計することで、同様の効果を得ることができます。例：

// Jenkinsfile内

parameters {
    booleanParam(name: 'SKIP_SETUP_STAGE', defaultValue: false, description: '初期セットアップステージをスキップします')
}

pipeline {
    agent any
    stages {
        stage('Setup') {
            when {
                expression { !params.SKIP_SETUP_STAGE }
            }
            steps {
                echo 'セットアップを実行中...'
                // ... セットアップステップ ...
            }
        }
        stage('Build') {
            steps {
                echo 'アプリケーションをビルド中...'
                // ... ビルドステップ ...
            }
        }
        // ... その他のステージ ...
    }
}

その後、CLI経由でこのパラメータ付きビルドをトリガーして、「Setup」ステージをスキップできます。

jcli build MyPipelineJob -p SKIP_SETUP_STAGE=true

このアプローチはJenkinsfileの設計において事前の考慮が必要ですが、CLIを介したパイプライン実行に対する強力な制御を提供します。

Groovy (CLI経由) を使用した高度なトラブルシューティング

groovyおよびgroovy-scriptコマンドを使用すると、任意のGroovyコードをJenkinsコントローラーで実行できます。これにより、Jenkinsの内部APIに比類のないアクセスが可能になり、詳細な検査と操作を行えます。

例: ビルド詳細の取得

```bash
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"

環境変数を検査し、ビルドの効率的なトリガーに関するコマンドを習得することで、ビルドの失敗の診断と解決にかかる時間を大幅に短縮できます。これらのCLI技術を日常のワークフローに統合して、高性能で信頼性の高いCI/CDパイプラインを維持してください。

広範なJenkins CLIコマンドリスト（jcli help）とGroovyスクリプトのパワーをさらに探求し、より高度な自動化とトラブルシューティング機能を解き放ちましょう。