Upgrade Jira Data Center 10 to 11 with minimal downtime

Summary

This article is concerned with upgrading Jira Data Center version 10 to version 11 with minimal downtime. Previous Jira version upgrades have required manual database updates, but no manual database upgrades are necessary when upgrading Jira 10 -> 11.

Upgrade steps overview

Here's a general outline of the steps we need to take to perform the upgrade:

1. Perform full reindex in an auxiliary temporary instance

   1. Setup a temporary Jira instance

   2. Overwrite some configs

   3. Startup auxiliary Jira and upgrade to Jira 11

   4. Kick-off full reindex and copy snapshot

2. Run upgrade procedure in production

   1. Set config to bypass automatic reindex

   2. Upgrade Jira in one node

   3. Copy the index snapshot to Production and restart

   4. Validate and upgrade the other nodes

   5. Change configs and restart Production Jira

Detailed Jira 10 -> 11 upgrade steps

1. Perform a full reindex in an auxiliary temporary instance

1.a. Copy the Production DB to a temporary new DB instance

Create a copy of Jira database. How to do that depends on the engine used. Please follow the engine-specific documentation to complete this step.

Do not use the Production DB for this procedure — the temporary/auxiliary Jira instance will perform DB data updates that would prevent other Jira 8 instances from using the same DB.

1.b. Overwrite some external-related data

When copying data from production to a non-prod environment, we advise overwriting some data to prevent users from inadvertently navigating from the non-prod instance to the Prod instance (like following links that point to Production URL).

These data overwriting steps are described in our Creating a test environment for Jira article.

For the purpose of this index generation, though, it's important to have data as close as possible to Production's, so you may overwrite only some integration-specific data like WebHooks, DVCS configs, etc.

These are some overwrites you can perform on the Production DB copy once it's restored to a temporary DB instance:

And the commands listed on Remove an application link from Jira server using SQL.

1.c. Setup a temporary Jira instance

With the DB copied, you may now work on creating a temporary Jira instance to run the upgrade and the full reindex on the copied DB.

Again you can rely on the steps outlined on Creating a test environment for Jira article:

For simplification, the shared-home folder of the temporary instance can even be configured in the local filesystem as we won't even spin up other nodes — just a single node to run the upgrade and full reindex.

1.d. Overwrite some configs

Make sure you have a jira-config.properties file in the new instance's jira-home with at least this line below:

upgrade.reindex.allowed=false

Also, add these flags to the JVM startup properties:

These properties are usually set through the setenv.sh/bat or in the service configuration:

Note all these configs should be present both in the Jira 10 and Jira 11 files.

1.e. Startup auxiliary Jira and upgrade to Jira 11

You may now startup Jira on the temporary node. It should still be Jira 10, just like Production.

It's advised you perform a full reindex as soon as the node comes up.

Since this is a non-prod instance with Production data, keep in mind the system properties from step 1.e should also be configured when bringing up Jira 11 (you may need to re-apply them after the upgrade and before bringing Jira 11 up for the first time on this temporary instance).

1.f. Kick off full reindex and copy snapshot

Once Jira's upgraded following the guides above and all incompatible apps have also been upgraded to compatible versions and re-enabled, you may kick off a full reindex.

Full reindex completion in atlassian-jira.log

[c.a.j.index.request.DefaultReindexRequestManager] Re-indexing finished

If Jira's Data Center licensed and configured with a shared-home in the cluster.properties, the index snapshot should've been created in the /<shared-home>/caches/indexesV2/snapshots/ folder.

If Jira's Server licensed or a Data Center without the cluster.properties, a snapshot must be manually created through System/Indexing and by setting the Index Recovery setting to a daily schedule in a near time in the future. The index snapshot will be created as scheduled in the /<jira-home>/caches/indexesV2/snapshots/ folder.

Once the index snapshot's created, you may bring down this instance and the DB to avoid inadvertent usage. Also copy the index snapshot to a safe location as backup.

2. Upgrade Production Jira

This is now during the Production maintenance window with Jira downtime.

2.a. Set configs to bypass automatic reindex

You should add these System Properties to the Jira 11 setenv.sh/bat or service parameters:

As well as the jira-config.properties:

upgrade.reindex.allowed=false

Ensure that you have a Shared Jira Home Directory and the file cluster.properties created in the local Jira Home directory. See Set up a Jira Data Center cluster for how to create this file and directory.

2.b. Upgrade Jira in one node

In this step, you will run the upgrade procedure described in the linked document below. Jira will be upgraded without a compulsory re-indexing step with the help of the above parameters. Using JQL/Boards etc will not be possible as you will start the upgraded node without Jira 11 index files but administrative actions can be performed.

Remember to disable incompatible apps before bringing down Jira 10 in Production, and stop all other nodes before doing so as described in the document. Upon Jira 11's successful startup, you may update the incompatible apps and enable them. Be sure the versions of the applications are the same as the applications on the temporary instance. Then, stop Jira on that node.

2.c. Copy the index snapshot to Production and restart

You may now copy the index snapshot generated by the temporary instance into the /<shared-home>/caches/indexesV2/snapshots/ folder.

You may start up Jira 11 on the first node again and it should pick up the index snapshot from the shared home. It'll re-index the "delta" of changes from the snapshot until the most recent operation in the database in multiple threads thus the closer the DB copy and index snapshot creation are to the Production upgrade, the better.

Index snapshot successful usage in atlassian-jira.log

2.d. Validate and upgrade the other nodes

You may now perform JQL searches in Production to confirm the Issues are showing up on filter results. This indicates the Index is present and operational.

You may now perform the upgrade on all the other nodes and they'll automatically pick up the same index snapshot and process the delta.

Alternatively, you may also stop this node again and copy the /local-home/caches/indexesV2 entire folder to the other nodes to speed up even more the startup as the other nodes won't need to process the delta.

Bring the node up again after copying the indexesV2 folder from it, if you choose to do so, then upgrade the others.

2.e. Change configs and restart Production Jira

Once the entire cluster is upgraded, we advise removing these configs so Jira 11 benefits from its default index startup strategy:

This can be done in the next maintenance opportunity.