要約

This KB article focuses on some specific and more practical aspects of the upgrade to Jira 9 and is intended as additional material to the official upgrade guide:

• Jira 9.4 長期サポート リリースのアップグレード ガイド
• Jira 9.12 への準備

以下のその他の記事も必ず参照してアップグレードを計画してください。

• 9.4 へのアップグレードに備えて Jira を準備する
• Jira Data Center を 9.4 にアップグレードする
• Jira Server を 9.4 にアップグレードする

You should first run the upgrade in lower environments to familiarize yourself with the upgrade steps, validate if your specific setup requires any additional steps, and validate if the new version and compatible apps behave as expected and meet your requirements.

Please contact Atlassian Support if you have questions after reading the materials or have problems upgrading the lower environments.

環境

Jira Software (JSW) Data Center 8 から 9

Jira Service Management (JSM) Data Center 4 から 5

ソリューション

主なポイント

Jira 7 から 8 へのアップグレードと比較した場合のポイントは以下の通りです。

• Incompatible apps should be turned off as they may prevent a successful startup.
• 起動時の自動完全再インデックス化を防ぐために、新しいフラグが必要です。
• 完全再インデックス化にかかる時間は、Jira 8 よりも大幅に長くなる可能性があります (メンテナンス ウィンドウが延びる可能性があります)。

その他の特記事項

• As a Platform Release upgrade, there's no ZDU (Zero Downtime Upgrade): the whole cluster needs to be down.
• The Jira 9 Index is incompatible with Jira 8's, so a full (foreground) reindex must be performed after Jira 9 is up and running before it's released to the users.

Last, some Platform Release upgrades best-practices:

• Set up an Internal Directory System Admin account to mitigate the risk of being unable to log in if the User Directory fails. You may need to temporarily disable or allow bypassing of SAML/SSO, too.
• Configure an alternate connector in Jira's Tomcat (through the server.xml) to allow bypassing the reverse proxy. Jira may respond "MAINTENANCE" on the /status endpoint (used by Load Balancers) until it has a healthy index and only a proxy-bypassing connector would allow the admin to login (if the automatic full reindex has been turned off through the new flags).

一般的なアップグレード手順例 (ZDU なし)

1. Check the supported platforms
2. バンドルされている App Update Check を実行する
3. カスタマイズをコピー (マージ) する
4. 自動完全再インデックスを回避するための JVM フラグを追加する
5. Bypass Load Balancer checks
6. 互換性のないアプリを無効化する
7. Jira を停止する (すべてのノード)
8. DB と Jira のホームフォルダをバックアップする
9. Jira 9 を 1 つのノードだけで起動する 
10. Log in as an admin and first update and then enable the apps disabled on step 6
11. Kick off a full (foreground) reindex
12. 検証
13. Start the Jira 9 on other nodes one by one
14. Migrate log4j configs (if needed)

1. Check the supported platforms

Check the Supported Platforms of the version of Jira you're upgrading to and confirm you meet the requirements (version dropdown selector on the top of the article):

• サポート対象プラットフォーム

If you don't meet any requirements (like Java version, DB version, etc.), you should first upgrade the platforms and then upgrade Jira.

If you need to skip too many versions, you may need to upgrade the platforms first, then Jira to an intermediate version, then the platforms again, and then Jira again to the final version.

2。 アプリの更新チェック

The App Update Check is a powerful built-in feature available through the Manage Apps screen (more on Checking app compatibility with application updates). It checks the compatibility of all apps against a selected destination Jira version.

No changes are performed during these checks, so running it at any time in Production is safe.

Jira Update Check の例のスクリーンショット:

この App Update Check は、「アップグレードの準備」の記事でも列挙されています。この記事も参照してください。

Alternatively, you may consider updating the apps listed under "Compatible if updated" in a maintenance window (at least some days) before the Jira upgrade. You should do these updates in a lower environment first to ensure the new apps' versions work as expected.

3. カスタマイズを上書き (マージ) する

Also, as part of regular upgrades, you should manually edit the Jira 9 files customized in Jira 8.

「別のサーバーへの Jira アプリケーションの移行」より:

通常は次のようなファイルを変更します。

• server.xml
• dbconfig.xml
• jira-config.properties
• setenv.sh / setenv.bat (メモリ割り当ておよびその他の JVM 引数)
• 詳細は「Jira の重要なファイル」をご参照ください。
  

よく修正されるファイルと Jira インストール ディレクトリ 内にあるそれらの場所の完全なリストは「 Jira の重要なファイル 」をご参照ください。

The DB drivers (usually for Oracle or MySQL DB) should also be copied.

4. 自動完全再インデックスを回避するための JVM フラグを追加する

Jira 8 では、「jira-config.properties」のエントリの「upgrade.reindex.allowed=false」により、インデックスなしの起動が許可されていました。

In Jira 9, this config only works for the first-ever startup — the one running (or had run) the DB update tasks. If the node's restarted (for whatever reason), Jira 9 will understand it's no longer an "upgrade startup" and enforce a full reindex upon startup. This has been raised through:

JRASERVER-74882 - Getting issue details... STATUS

To guarantee Jira 9 won't kick off a full reindex on subsequent restarts during the upgrade maintenance window, add these two Opts to the JVM startup params before starting Jira 9 for the first time:

-Dcom.atlassian.jira.startup.allow.full.reindex=false 
-Dcom.atlassian.jira.startup.rebuild.local.index=false

これらを setenv.sh/bat ファイルの JVM_SUPPORT_RECOMMENDED_ARGS に追加できます (スペース文字で区切って、そこの他のパラメータに追加)。

JVM_SUPPORT_RECOMMENDED_ARGS="-Dcom.atlassian.jira.startup.allow.full.reindex=false -Dcom.atlassian.jira.startup.rebuild.local.index=false"

And add this to the jira-config.properties file to avoid the Full Reindex on the very first startup in Jira 9 (you may need to create the file if it doesn't exist — see Advanced Jira application configuration):

upgrade.reindex.allowed=false

Please have a look at the article on Setting properties and options on startup for an overview of setting JVM flags.

これら 2 つのフラグは、このような起動画面をトリガーします (すべての警告を無視して続行します)。

Once the upgrade's over, you should remove those flags so Jira 9 behaves as expected on all subsequent restarts, optimizing Index acquisition and delta catch-up with multiple Threads. Nodes will rely on their local indexes and fall back to the shared-home snapshots when needed.

For more details on the Index startup strategy introduced in Jira 9.4, please look at the Index startup procedure in Jira 9.4 and later.

5. Bypass Load Balancer checks

Since we're forcing Jira not to perform the Full Reindex on startup, Admins should be able to log in to Jira to update required apps and kick off the Full Reindex manually.

If you don't have a Proxy/Load-Balancer bypassing connector on Tomcat, you may not be able to access Jira through the Browser because, since 8.19, Jira responds "Maintenance" to the /status URL if its Indexes aren't healthy.

To work around this, you need to either:

a. Configure a bypass connector in the server.xml and access Jira through its IP:port on the browser

• Refer to Bypass a proxy or SSL to test network connectivity for Jira Server and Data Center

Regardless of the upgrade, this alternate connector is good to have, as it facilitates troubleshooting several performance and UI glitches in Jira. (by testing direct Browser connection to Jira)

You should add this connector before the upgrade and validate it's working.

または

b. Add a temporary JVM Opt to bypass the Index Consistency Checks

You may add this parameter together with the others from step 4:

-Dcom.atlassian.jira.status.index.check=false

If you already had this option (to workaround JRASERVER-73281, for example), you can keep it.

If not, you should remove it as soon as the upgrade is completed — this is a critical feature in Jira and should only be applied if you can't setup an alternate connector in time for the upgrade and Jira's behind a Load-Balancer using the /status endpoint to validate if the node's online.

6. 互換性のないアプリを無効化する

Some Jira 8 apps are incompatible with Jira 9, so they may compromise Jira startup.

Before bringing all nodes down for the upgrade, we should turn off all apps listed under any of these categories in the Update Check:

• Incompatible
• Compatible if updated
• Compatible once both Jira and the app are updated

We'll update and enable them once Jira 9 comes up and only then kick off the full reindex.

Given this impact, this step may be considered the start of Jira unavailability during the maintenance window.

7. Jira を停止する (すべてのノード)

Jira は、「プラットフォーム リリース」間 (7.x から 8.x、8.x から 9.x など) 間の ZDU (Zero-Downtime Upgrades) をサポートしていないため、いずれかのノードでアップグレードを開始する前にすべてのノードを停止させる必要があります。

Also, don't put the cluster in "upgrade mode" — this feature is only for ZDU, and enabling it may compromise the upgrade procedure. It should only be enabled when upgrading Jira within the same Platform Release, like from 8.0.0 to any version up to 8.22.99* or 9.0.0 to 9.99.99*

*バージョン範囲を説明するための仮想のバージョンです。

8. DB と Jira のホームフォルダをバックアップする

With Jira down, performing a backup of the local home folder and the database is safe now.

If Jira is not configured with the cluster.properties (requires Jira Data Center license), the attachments may be located within the local home folder, and its backup may extend the maintenance window considerably. If so, you may consider backing up the attachments folder before bringing the nodes down and excluding the folder from the backup on this "step 6".

Please refer to Set up a Jira Data Center cluster to learn how to set up a Jira cluster. You may even set up a "single node cluster, " but you will still benefit from the shared-home design.

If the attachments were backup up previously, you may exclude them from this step to save time.

9. Jira 9 を 1 つのノードだけで起動する

Jira 9 should be started up only in one node. It'll perform the upgrade tasks, including altering the DB tables to add more columns and creating missing version records for entities like Issues, Comments, and Worklogs.

これらのアップグレード タスクのため、この起動は、その後の Jira 9 の起動よりも時間がかかると予想されます。

Wait to start other nodes until the first node's up and the manual full reindex has been completed.

10. Log in as an admin and first update and then enable the apps disabled on step 6

Once the first node is up and running, you may access it through the browser as an admin, first upgrade each app disabled in step 6, and then enable them.

It's essential to run this through UAT sometime in advance as some apps may have become paid when upgrading them to Jira 9.X compatible versions.

To reduce login issues, you should set up a local admin account (in the Internal Directory) and temporarily configure SAML/SSO bypassing (if you have them) to avoid being locked out of the instance.

Also, it's advised to configure an alternate Tomcat connector to bypass the reverse proxy and access the node's Tomcat directly, as Jira 9 will respond MAINTENANCE on the /status endpoint to the Load Balancer until it has a healthy index of its own.

Refer to Bypass a proxy or SSL to test network connectivity for Jira Server and Data Center for more on this.

11. Kick off a full (foreground) reindex

Once all disabled apps have been updated to compatible versions and re-enabled, you may kick off the full reindex.

Please note some customers have observed a considerable increase in the full reindex duration from Jira 8 to Jira 9:

JRASERVER-74787 - Getting issue details... STATUS

Depending on how many entity versions and non-archived Issues Jira has, some customers reported a full reindex duration up to 3 times what was observed in Jira 8.20. This issue was fixed in 9.7.0 (JSM 5.7.0) and backported to Jira 9.4.6.

The good news is that the Jira 9 index is more reliable than Jira 8's, and admins shouldn't need to perform full reindex as regularly as they had on Jira 8 — and even then, it shouldn't have been required so much since Jira 8.13!

See our article on Periodic full reindex in Jira Data Center is not required for more. If you still have to perform regular full reindexes to fix unexpected behavior in Jira 8.13 – 8.22, please contact Atlassian Support so we can troubleshoot this!

12. 検証

Once the full reindex is completed in the first node, admins may perform the usual post-upgrade validations they're used to.

This may include creating and changing the status of some test Issues, validating critical apps and features, and confirming the bundled Health Check's reporting is all good.

13. Start the other nodes one by one

Now, the other nodes may be upgraded and started up individually.

インストーラーまたは手動アップグレード (tar.gz/zip) による、最初のノードで実行したのと同じプロセスです。

• Jira のアップグレード (インストーラー)
• Jira のアップグレード (手動)

ステップ 2 のカスタマイズも各ノードに移植する必要があります。ただし、ステップ 3 の 2 つの新しい JVM フラグは技術的に無視できます (これらは、最初の Jira 9 のインデックスの完全再作成が実行されるまで作業中の単一ノードにのみ関係します)。

ノードが起動すると、共有ホームから最近生成されたインデックス スナップショット (最初のノードの手動インデックス再作成で作成) をフェッチして、できるだけ早く利用できるようになります。

-Dcom.atlassian.jira.startup.allow.full.reindex=false
-Dcom.atlassian.jira.startup.rebuild.local.index=false

14. Migrate log4j configs (if needed)

If upgrading to JSW 9.5 / JSM 5.5 or above, you should port over custom changes you may have made to the log4j.properties.

Jira SW 9.5 / SM 5.5 bundles Log4j 2, and its configuration file is an XML, not the .properties file from Log4j 1.2.

You can refer to this article on Migrating custom logging configurations to Log4j 2 to port over custom loggers if needed. We advise doing this post-upgrade once Jira's stable to isolate any impacts from log4j2 misconfiguration from the upgrade.