Jenkinsのバージョンアップについての注意点をまとめてみた

こんにちは。テクマトリックスの長久保です。
バージョンアップって何かとネガティブですよね。
今回はそんなJenkinsのバージョンアップについて、ハマりそうなポイントについて記載していきます。

なお、Jenkins 2.375.2を利用し、2023/02/21時点の情報を元に作成しております。
JenkinsのUIやエラーメッセージ、アラートメッセージなどの変更があった場合、適宜読み替えて実施してください。

バージョンアップ基本手順

以下の手順でバージョンアップすることが多いかと思います。

Jenkinsを停止する
JENKINS_HOMEのバックアップを取得する
Jenkinsのバージョンを上げる
・warファイルで実行している場合はjenkins.warファイルを差し替える。
・コンテナで実行している場合はコンテナをビルドし、マウント先を今まで利用していたところに指定する、等。
Jenkinsを起動する

これでうまくいけば何も問題ありません。また多くの場合これでうまくいくと思います。
しかし、何世代にもまたがったバージョンアップや様々な設定がされたJenkins環境でバージョンアップを行った場合、問題になる場合があります。

そんな起きうる問題と対策についていくつか紹介します。

バージョンアップ時に最低限実施したほうが良い事

まずバージョンアップする前に行う事について記載します。

理想を言えば影響するJenkins LTS Upgrade Guideのすべてに目を通し影響範囲を確認し、利用中のプラグインのReleasesタブからすべての変更履歴を確認して問題がない事を確認すると良いです。しかし、長期間バージョンアップされておらず、確認箇所が多い場合はそれだけでバージョンアップの意欲がそがれてしまうでしょう。

ここではバージョンアップ時に最低限実施したほうが良い事を記載します。

JENKINS_HOMEのバックアップを取得する

JENKINS_HOMEにはJenkinsの設定ファイルが保存されています。
JENKINS_HOMEさえあれば、何か問題があっても元の状態に戻すことができます。バージョンアップ前には必ずJENKINS_HOMEを取得しましょう。
JENKINS_HOMEの場所がわからない場合、Jenkinsダッシュボード > Jenkinsの管理 > システムの設定 > ホームディレクトリの欄で確認できます。

JENKINS_HOMEに含まれる情報については、こちらをご覧ください。
Explaining $JENKINS_HOME

プラグインについて確認する

警告が表示されていないか確認する

Jenkinsダッシュボード > Jenkinsの管理 > プラグインの管理 > Updateタブを参照ください。
アップデートによるリスクがあるプラグインについては、以下のように警告が表示されています。

基本的にはすべてのプラグインは最新に保つほうが良いですが、警告の内容に拠ってはバージョンアップをしないという選択肢を取るものもあるかもしれません。ただその場合、依存するプラグインやJenkinsの要求バージョンを考慮する必要がありますので、必ずプラグインのページを確認しましょう。

deprecated扱いになっていないか確認する

利用中のプラグインが最新のバージョンではdeprecated扱いになっていることもあります。Jenkinsのコアに統合されたため不要になったり、統合先のプラグインと対応方法が明記されているものもありますが、そうでないものもあります。
deprecated扱いになったプラグインの影響度は利用中の環境に依存しますが、対応方法について検討してからバージョンアップをしたほうが良いでしょう。
確認方法についてはDeprecating or removing a Pluginのページを確認するか、Jenkinsの管理でも確認できます。
deprecated扱いになったプラグインは以下のように情報が表示されます。

バージョンアップ検証環境を作成する

Jenkinsに限った話ではないですが、いきなり本番環境でのバージョンアップは避けるべきです。Jenkinsは様々な環境で構築ができます。検証用にJenkinsを構築し、JENKINS_HOMEを本番環境のもので差し替えれば検証環境を作成することができますので、その環境でプラグインのバージョンアップやジョブの検証を実施した後に本番環境をバージョンアップすると良いでしょう。

さて、次からはバージョンアップを行った際に起きうる問題と対策について紹介していきます。
Jenkinsは1800を超えるプラグインが存在しますし、独自にカスタマイズしている場合もあるかと思います。
環境依存の問題も多くあるため、一概に「こうすれば解決する」というものではないですが、少しでも参考になれば幸いです。

問題：そもそもJenkinsが起動しない Part.1

2.357および、2.361.1 LTS以降のJenkinsではJava8のサポートが終了しています。
そのため、Jenkinsの実行環境をJava8のままJenkinsのバージョンを上げるとJavaのバージョン違いによるエラーにより起動に失敗します。
詳しくはこちらのブログを参照ください。

Sep 08, 2022 7:38:49 AM executable.Main verifyJavaVersion
SEVERE: Running with Java class version 52, which is older than the Minimum required version 55. See https://jenkins.io/redirect/java-support/
java.lang.UnsupportedClassVersionError: 52.0
at executable.Main.verifyJavaVersion(Main.java:145)
at executable.Main.main(Main.java:109)
Jenkins requires Java versions [17, 11] but you are running with Java 1.8 from /opt/java/openjdk/jre
java.lang.UnsupportedClassVersionError: 52.0
at executable.Main.verifyJavaVersion(Main.java:145)
at executable.Main.main(Main.java:109)

対策：JDKのバージョンを上げる

ログの情報に従い、Jenkinsの実行環境のJavaのバージョン11または17に上げてから、再度Jenkinsを起動してください。
具体的な手順はこちらのページも併せてご確認ください。
Upgrading Jenkins Java version from 8 to 11

問題：そもそもJenkinsが起動しない Part.2

Javaのバージョンアップに伴い、廃止になった実行時引数が様々あります。
例えば、私個人としては以下のVMオプションはなじみが深いものですが、JDK8で削除されており、JDK11環境で実行すると警告が表示されます。

-XX:MaxPermSize=size
-XX:PermSize=size

対策：廃止されたJavaの実行時引数を削除、または有効な書き方に修正する。

デフォルトのガーベジ・コレクタがJDK9以降変更になっており、起動に失敗する組み合わせもあるとの事です。
Jenkinsの起動時に様々なJavaオプションをつけている場合、ご利用のJDKに合わせた移行ガイド(例：Oracle JDK 移行ガイド)などをご確認ください。

問題：起動はしたが、ログイン画面が表示されない

Jenkinsは起動し、ブラウザでアクセスできたが画面一面にエラーログが表示されれるというケースです。

WARNING hudson.ExtensionFinder$Sezpoz#scout: Failed to scout org.jenkinsci.plugins.gitserver.ssh.SshCommandFactoryImpl

com.thoughtworks.xstream.mapper.CannotResolveClassException: hudson.security.GlobalMatrixAuthorizationStrategy

java.lang.IllegalStateException: An attempt to save the global configuration was made before it was loaded

WARNING h.ExtensionFinder$GuiceFinder$SezpozModule#configure: Failed to load hudson.security.LDAPSecurityRealm$DescriptorImpl

画面一覧に「エラー」と表示されるのは少し悲しいです。

ケースバイケースのためログを確認し解消していくことになりますが、この場合プラグインが悪さをしていることが多いです。
例えば長期間バージョンアップをせず、JDK11で動作しないプラグインが有効になっていればエラーになります。

対策1：元々のバージョンのJenkinsでプラグインのバージョンアップを可能な限り行い移行する

このようなエラーになり、ログの内容からプラグインが怪しそうな場合、いきなり最上位までプラグインのバージョンを上げるのではなく、従来のJenkinsのバージョンでプラグインのバージョンを上げてから移行するのが良いでしょう。

ただ、別のJenkins環境でプラグインをバージョンアップし、バージョンアップ後のpluginsフォルダだけ差し替えるという場合は注意が必要です。
プラグインの実体はJENKINS_HOMEの中のpluginsフォルダ内のjpi(またはhpi)と同名のフォルダですが、しかし例えばMatrix Authorization Strategyの設定はpluginsフォルダ外(JENKINS_HOMEのconfig.xml)に保存されています。
プラグインのバージョンと設定の記述が合致しない場合、起動しないこともあります。
各プラグインの設定がどこまで影響するかは各プラグインに依存するため、プラグインバージョンアップ後、可能であればpluginsフォルダのみではなくJENKINS_HOMEごと差し替えましょう。

また、あまりに現行のバージョンとバージョンアップのターゲットバージョンが離れている場合、Jenkins LTS Upgrade Guideを参考に、各マイナーバージョンごとに段階を踏みながらJenkinsとプラグインそれぞれのバージョンアップをしていくとより安全です。

対策2：ログを確認して問題を切り分ける

Failed to instantiate Key[type=jenkins.security.plugins.ldap.LDAPConfiguration$LDAPConfigurationDescriptor,

地道な作業ですが、ログの確認は大切です。

プラグインのGitHubリポジトリのIssuesで重要な情報が見つかることもあります。
例えば上記の先ほどのログを確認していくと
Error when starting jenkins on docker container using jasc
このページにたどり着くことができます。

また問題切り分けの際にプラグインを無効化して原因かどうか確認したいという場合もあるかと思います。
プラグインの実体はJENKINS_HOME > pluginsフォルダ内のjpi(またはhpi)と同名のフォルダです。表示されているエラーに関わるプラグインを削除や退避することで起動を妨げているプラグインを除外できます。

問題：プラグインが更新できない

プラグインを更新しようとプラグインのページを開いたところ、以下のような警告が表示されている場合があります。

There were errors checking the update sites: SocketTimeoutException: connection time out

この状態でプラグインの更新をしようとしてもダウンロードできず更新に失敗します。

対策1：Javaのマイナーバージョンを疑う

例えばJava11でもマイナーバージョンが古いものを利用している場合、JenkinsのUpdate Centerとの疎通が認証系のエラーによって失敗する場合があります。最新のJava11にバージョンを上げ、再度確認してみて下さい。

対策2：プロキシを疑う

長い間プラグインの更新をかけていなかった場合、元々アップデートを行うためのサーバーに接続できていなかったという事も考えられます。Jenkinsダッシュボード > プラグインの管理 > Advanced settingsからHttp Proxyの設定ができますので、こちらの確認をしてみて下さい。

対策3：アップデートサイトのURLを確認する

Jenkinsダッシュボード > プラグインの管理 > Advanced settingsのアップデートサイトの欄を確認ください。Unable to connect to the URL等エラーが表示されていれば、URLが誤っている可能性もあります。
一度欄を空にするとReset to defaultとクリック可能なリンクが表示されるので、こちらをクリックしてURLの初期化を試みて下さい。

対策4：ネットワークやファイアウォールを疑う

そもそもJenkinsのインストールしているマシンが外部にアクセスできるかの確認も必要です。少なくともhttps://updates.jenkins.io/update-center.jsonにアクセスできる必要があります。

問題：エージェントとの疎通ができない

対策：Java Web Startでの接続をしていないか確認する

$ java -jar slave.jar -jnlpUrl http://yourserver:port/computer/slave-name/slave-agent.jnlp

上記の様にjnlpを用いてエージェントを接続している場合です。Java Web StartはJava11では廃止になりました。そのため、Java Web Startを利用してエージェントとの接続をしていた場合、接続方法を変更する必要があります。

エージェントの接続方法については、以下ドキュメントも併せてご確認下さい。

補足：WMI Windows Agents プラグインを利用されている方向けの情報共有

WMI Windows Agents プラグインはWindows Management Instrumentation (WMI) を介して Windows マシンにエージェントをセットアップできるプラグインです。2023年2月7日時点で127,116回ダウンロードされている人気のプラグインなので、このブログを見ている方の中にも利用されている方もいるかと思います。
しかしこのプラグインは現在Deprecated扱いとなっており、廃止も決定されているようです。なるべく早く異なるエージェント接続への移行を推奨します。

問題：表示されていた項目が表示されない

対策：JenkinsのConfiguring Content Security Policyを確認する

Jenkinsのセキュリティのルールセットが厳しくなっている可能性があります。JenkinsのConfiguring Content Security Policyについてはこちらを確認下さい。
上記Configuring Content Security Policyのページにも記載がありますが、プロパティ値はJenkinsのスクリプトコンソールにてJenkinsの再起動無しに確認できます。

Jenkinsダッシュボード > Jenkinsの管理 > スクリプトコンソール

スクリプトコンソールを利用するとJenkinsの再起動無しに設定を変更できます。検証には便利です。
ただ、こちらのスクリプトコンソールで変更したプロパティ値はJenkinsを再起動するとJenkins起動時の状態に戻ってしまいます。
問題の切り分けが完了しプロパティ値を変更する場合は、Jenkinsの起動時のオプションに引数を追加して起動することを推奨します。

問題：「Some permission assignments are ambiguous.」というアラートが表示される。

対策：グローバルセキュリティの設定で設定を変更する。

Matrix Authorization Strategyプラグインの行列による権限設定をしている場合、この問題が発生することがあります。
Jenkinsの管理に「Some permission assignments are ambiguous.(省略)」というアラートが表示されます。

そのままでも利用はできますが、「permission」とついているので修正したい方も多いかと思います。
Jenkinsダッシュボード > Jenkinsの管理 > グローバルセキュリティの設定の画面を開くと「This table contains rows with ambiguous entries. This means that they apply to both users and groups of the specified name.(省略)」というメッセージが表示されています。
この権限設定に関わるMatrix Authorization StrategyプラグインはVersion3.0でユーザやグループでの権限設定ができるようになりました。
そのため、ユーザーなのかグループなのか明示的に示す必要があります。権限設定のマトリックスの右端に以下の様なアイコンがありますので、それぞれの権限ごとにユーザーかグループかの選択をしてください。

なお、この更新をしたのちに、Matrix Authorization StrategyプラグインをVersion3.0以下に落とした場合、Jenkinsにアクセスしても画面上にエラーが表示され、操作できなくなります(前述の「問題：起動はしたが、ログイン画面が表示されない」状態)。その場合手動でプラグインをVersion3.0以上に更新するか、セキュリティ設定を無効にし、再度プラグインの更新や権限設定を行う必要があります。

元のJenkinsおよびプラグインのバージョンに戻したい場合

バージョンアップ時に問題が発生し、環境を切り戻す際の方法について記載します。
バージョンアップ前のJENKINS_HOMEがある事を前提とします。

Jenkinsのダウングレード

バージョンアップと同じ方法で前の状態にJenkinsを戻します。例えばwarファイルでの実行であれば、元のバージョンのjenkins.warと差し替えます。その後、JENKINS_HOMEをバージョンアップ前のものと差し替え再起動します。

過去のバージョンのJenkinsはJenkinsの公式ページからも取得できますし、直前のバージョンアップ前のwarファイルはJenkinsダッシュボード > Jenkinsの管理からも取得できます。

切り戻し作業を行う際はJENKINS_HOMEごと切り戻しを行う事を推奨します。

特定のプラグインのダウングレード

前提

プラグインの中にはbreaking changeを伴う修正が行われているものもあります。
また、多くのプラグインは下記の方法によってダウングレードできますが、pluginsフォルダ内のみダウングレードをすると起動できなくなるプラグインもあります。具体例は下記の「ダウングレードで挙動が変わる(動作しなくなる)プラグイン」を参照ください。
プラグインのダウングレードをする際はプラグインページのReleasesタブなどを確認してから行う事を推奨します。

プラグインの仕組み

基本的にプラグインの実体はJENKINS_HOME > pluginsフォルダ内のjpi(またはhpi)と同名のフォルダです。
例えばEmail Extensionプラグインはemail-ext.jpiとemail-extフォルダになります。

以下にいくつかダウングレードの手順を記載します。

プラグインのページからダウングレードする

Jenkinsダッシュボード > Jenkinsの管理 > プラグインの管理 > Installed Pluginsを選択し、ダウングレードのボタンを押下してください。任意のバージョンへのダウングレードはできませんが、以前利用していたバージョンへのダウングレードが可能です。

pluginsフォルダの内容を直接差し替える

バージョンアップ前のJENKINS_HOMEからjpi(またはhpi)と同名のフォルダを取得し、差し替えます。

ブラウザ上からプラグインのデプロイを行う

Jenkinsダッシュボード > Jenkinsの管理 > プラグインの管理 > Advanced settings > Deploy Pluginにてローカルファイルのjpi(またはhpi)、またはJenkinsの中央プラグインリポジトリからインストールできます。

Jenkins CLIを利用する

Jenkinsダッシュボード > Jenkinsの管理 > Jenkins CLI のinstall-pluginコマンドを利用することでインストールが可能です。詳細についてはJenkins CLIのページ(http://{Jenkins_url}/manage/cli/command/install-plugin)を参照ください。

プラグインのダウングレード時の注意

プラグインのダウングレードは一般的に推奨されません。ダウングレード時には以下の点に注意をしてください。

依存プラグイン

プラグインにはプラグイン間で依存関係にあるものがあります。どのプラグインが依存関係にあるかは各プラグインのページに記載があります。
例えばEmail ExtensionプラグインのDependencisタブを参照ください。

ダウングレードする場合は依存関係にあるプラグインも併せてダウングレードする必要がある場合があります。

ダウングレードで挙動が変わる(動作しなくなる)プラグイン

例として、Matrix Authorization Strategyプラグインが挙げられます。

This release uses a new on-disk format for permissions inheritance options. Existing options will be retained when upgrading, but downgrading to older versions may result in failures to load job or folder permission data, or different (typically additional) permissions being granted after the downgrade.
https://github.com/jenkinsci/matrix-auth-plugin/blob/master/CHANGELOG.md#important-upgrade-notes

このようにプラグインによってはダウングレード時の注意が明記されているものもありますので、ダウングレードする場合には必ず対象のプラグインを確認してからのダウングレードを推奨します。

まとめ

Jenkinsに限らずですが、大きなバージョンをまたいだバージョンアップは問題が起きるリスクが高くなると言えます。Jenkinsはクローズドのネットワークで利用されることが多く、すでにJenkins自体が安定していることもあり、バージョンアップされずに利用されることが多い印象ですが、基本は定期的にバージョンアップをすることを推奨します。

Jenkinsの更新には大きく3種類あります。

LTS(Long-term Support)：安定版。通常12週に一度リリースされる。
レギュラーリリース：バグ修正・新規機能追加。通常週1回リリースされる。
セキュリティリリース：緊急性のある修正版。

LTSがリリースされる度ではなくとも、例えばマイナーバージョンが2.361.xから2.375.xに挙がったタイミングでバージョンアップを検討すると良いでしょう。

JDK8のサポート期限の話もありますし(例：OpenJDK8)、Jenkins自体も、例えばお天気アイコンも新しくなっています。

もしまだ古いアイコンのままのJenkinsを利用されている方は、この機会にバージョンアップをされてはいかがでしょうか。

宣伝

テクマトリックスではJenkinsの有償サポートも実施しています。

こういったバージョンアップなどの困りごと等、Jenkinsに関わる質問がありましたら、ぜひこちらのページよりお問合せ下さい。