DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ

再起動不要でJenkins設定を安全にリロードする方法

Jenkinsの設定をディスクから安全にリロードし、安全な再起動が適切なタイミングを見極め、リスクの高いScript Consoleのショートカットを避ける方法を解説します。

再起動不要でJenkins設定を安全にリロードする方法

Jenkinsの設定をリロードすることは、忙しいコントローラ上で実行し、ジョブが実行中にすべての変更をクリーンに適用できるわけではないと気づくまでは無害に聞こえます。適切なコマンドは、何が変更されたかによって異なります。

JENKINS_HOME内のXMLファイルを編集した場合、バックアップからジョブを復元した場合、またはWeb UI外でファイルを変更した場合、Jenkinsはディスクから設定をリロードできます。プラグインをインストールまたはアップグレードした場合、Javaオプションを変更した場合、またはランタイム状態をリフレッシュする必要がある場合、通常は安全な再起動がより適切なツールです。これらは異なる操作です。

避けるべき誤解を招くショートカットは、Script ConsoleでのSystem.exit(10)です。これは、Jenkinsの起動方法によっては、プロセススーパーバイザー、サーブレットコンテナ、またはサービスラッパーがJenkinsを再起動する原因となる可能性がありますが、クリーンな「設定のリロード」コマンドではありません。作業を中断する可能性があり、意図を隠します。代わりにJenkins CLIまたは組み込みの管理アクションを使用してください。

CLIを使用してディスクから設定をリロードする

最も明確なコマンドはreload-configurationです：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration

これにより、Jenkinsはロードされた設定を破棄し、ディスクから再度読み取ります。これは、ジョブ設定の復元や自動化によって生成された設定の適用など、制御されたファイル変更の後に役立ちます。

実行する前に、3つのことを確認してください：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" who-am-i
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs >/dev/null

設定のリロードには、アカウントに管理権限が必要です。日常的な自動化に誰かのラップトップからの個人用管理トークンを使用しないでください。管理された管理アカウントを使用し、トークンをシークレットストアに保管し、ポリシーに従ってローテーションしてください。

Web UIを希望する場合は、Manage Jenkinsと、Jenkinsのバージョンとインストールされたコンポーネントで利用可能な場合のリロードオプションを使用してください。CLIは、コマンドをランブックに保存できるため、監査が容易です。

安全な再起動がより適切な選択である場合

安全な再起動は、実行中のビルドが完了するのを待ってからJenkinsを再起動します。リロードよりも遅いですが、ランタイム状態を再構築する必要がある場合にはより正直です。

プラグインのインストールまたはアップグレード後、Javaオプションの変更後、Jenkinsコアのアップグレード後、またはコントローラの完全再起動後にのみ現れる動作の後には、安全な再起動を使用してください。

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" safe-restart

環境が許可する場合は/safeRestartエンドポイントを使用することもできますが、CLI形式の方が標準化しやすいです。

ダウンタイムゼロを約束しないでください。リロードはUIに一時的に影響を与える可能性があり、安全な再起動はビルドがドレインされた後に意図的にコントローラを再起動します。エージェントが切断されたり、プラグインの動作がおかしい場合、ユーザーが気付く可能性があります。影響範囲が許容できるときに操作をスケジュールしてください。

より安全なリロードのランブック

まず、メンテナンスウィンドウをアナウンスしてください。たとえ短くても構いません。次に、何が実行されているかを確認します：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs

簡単なキュー確認には、CLI経由でGroovyを使用します：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" groovy = <<'EOF'
Jenkins.instance.queue.items.each { item ->
  println "Queued: ${item.task.fullDisplayName}"
}
Jenkins.instance.computers.each { computer ->
  computer.executors.findAll { it.isBusy() }.each { executor ->
    println "Running on ${computer.displayName}: ${executor.currentExecutable}"
  }
}
EOF

これから依存する設定をバックアップしてください。最低でも、JENKINS_HOME、特にconfig.xml、ジョブディレクトリ、資格情報メタデータ、プラグイン状態の最近のバックアップを用意してください。資格情報ファイルには注意してください。バックアップをシークレットとして保護してください。

リロードを実行します：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" reload-configuration

次に、コントローラが応答していることを確認します：

java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" who-am-i
java -jar jenkins-cli.jar -s "$JENKINS_URL" -auth "$JENKINS_USER:$JENKINS_API_TOKEN" list-jobs >/dev/null

作業が完了したと判断する前に、システムログと代表的なジョブを確認してください。成功を返すリロードでも、不良なジョブXML、欠落したプラグイン、または権限の問題が露呈する可能性があります。

Groovyリロードスクリプトについて

Script Consoleは、Jenkinsコントローラ内で実行されるため強力です。それが注意を要する理由でもあります。スクリプトコンソールユーザーは、シークレットの読み取り、ジョブの変更、セキュリティコントロールの無効化、またはコントローラの破損を行う可能性があります。

検査のためにGroovyが必要な場合は、読み取り専用で短く保ってください。例えば：

println Jenkins.instance.version
println Jenkins.instance.items.size()
println Jenkins.instance.queue.items.size()

使用しているJenkinsのバージョンとプラグインでテストしていない限り、文書化されていない内部リロード呼び出しは避けてください。内部APIは変更される可能性があり、プラグイン固有のリロードメソッドは、気にしている状態をリロードしない場合があります。

Configuration as Codeのセットアップでは、汎用的なJenkinsリロードではなく、プラグインの文書化されたリロードメカニズムを使用してください。JCasCには独自のモデルと検証動作があり、ディスク上で正しく見える設定ファイルでも適用に失敗する可能性があります。

リロードが失敗した場合の対処法

Jenkinsがジョブの欠落、ビューの破損、プラグインエラーで戻ってきた場合、リロードを繰り返さないでください。システムログを取得し、時刻を記録し、変更されたファイルをバックアップと比較してください。一般的な原因は、不正なXML、インストールされていないプラグインを参照するジョブ設定、またはJenkinsがまだファイルを書き込んでいる状態での手動編集です。

UIが不安定でもプロセスが実行されている場合、安全な再起動で一時的な状態がクリアされる可能性があります。設定が実際に不良である場合は、まず以前のファイルを復元し、その後リロードまたは再起動してください。

最も安全なパターンはシンプルです：ディスク設定の変更にはreload-configurationを、ランタイムとプラグインの変更にはsafe-restartを使用し、Script Consoleは1行ずつ説明できる意図的な管理スクリプトのために予約してください。