Managing zero downtime upgrades

If you're running JIRA Software Data Center 7.3 or above in a clustered environment, zero downtime upgrades allow you to upgrade your nodes with no downtime for your users i.e. your instance will remain available throughout the upgrade process. We'll explain what you need to do before you begin, and the procedure you need to follow to get your instance upgraded. We recommend you read this page and make sure you understand the process before starting your upgrade.

Note that JIRA Software 7.3 is the minimum version you need to be able to use this upgrade process.

Before you begin

Before you start your zero downtime upgrade, there's a few things you'll do:

Ensure you have the installer for your intended version.
  Tell me more...

Download the appropriate JIRA Software installer. Make sure you have it available for all your nodes, as you'll need it to upgrade them one at a time.

Ensure you know about your intended version.
  Tell me more...

Review the release notes and upgrade notes for the version of JIRA platform and JIRA Software that you're upgrading to. If you plan to skip a few versions during your upgrade, we strongly recommend that you read the release notes and upgrade guides for all versions between your current version and the version to which you are upgrading. Remember, the minimum version you need to be on to use zero downtime upgrades is JIRA Software 7.3.

Ensure you're on a supported platform.
  Tell me more...

Confirm that your operating system, database, and other applicable platforms and hardware still comply with the requirements for JIRA Software 7.3. The End of Support Announcements page also has important information regarding platform support for future versions of JIRA.

Ensure you check your add-ons.
  Tell me more...

If you have installed JIRA add-ons (i.e. not included with JIRA), verify that they will be compatible with the version of JIRA Software you are upgrading to. You can find add-on compatibility information on the add-on's home page on the Atlassian Marketplace

  • If the add-on currently supports your current and your intended version, you don't need to do anything.
  • If the add-on has an update available that supports your current and your intended version, update the add-on before you start your JIRA upgrade.
  • If the add-on supports your current version, but requires an update to support your intended version (and the update doesn't support your current version), you should disable the add-on to avoid any issues during the upgrade. Once the upgrade is complete and finalized, you can update and re-enable the add-on. This will mean the add-on is unavailable during the upgrade.
  • If the add-on supports your current version, but not your intended version (and there is no update available that supports your intended version), it may cause issues during the upgrade and should be disabled if you decide to proceed with your upgrade. You should not enable the add-on until such time as it supports your new version, and can be updated.
Back up your database
  Tell me more...

Zero downtime upgrades rely on the database being available throughout the upgrade process, so you should perform a database backup using your database's native tools as close to the start of your upgrade procedure as you can.

Ensure your Support Healthcheck and Instance Health plugins are enabled
  Tell me more...

Zero downtime upgrades checks rely on both of these plugins being enabled to make sure JIRA has the correct information to help you during your zero downtime upgrade. These are enabled by default, but to check you need to:

  1. Navigate to > Add-ons > Manage add-ons.
  2. Search for the plugins by entering "health" and selecting System for in the drop-down.
  3. Expand the relevant plugin to check if it's enabled or disabled. If disabled, enable it by clicking Enable.

Prestaging and testing your new version

We strongly recommend performing your upgrade in a test environment that best reflects your production environment first. Don't upgrade your production instance until you are satisfied that your test environment upgrade has been successful and is functioning correctly. This includes checking your add-ons and customizations. If you have any problems with your test environment upgrade which you can't resolve, create an issue at our support site so that we can assist you.

1. Put JIRA into upgrade mode

Putting JIRA into upgrade mode stops your instance from performing any long running tasks, such as indexing. Upgrade mode also allows the nodes in your cluster to run on different versions of JIRA Software until you finalize or cancel your upgrade. To put JIRA into upgrade mode, all your nodes need to be running on the same versions.

  1. Navigate to > Applications > JIRA upgrades.
  2. Click Put JIRA into upgrade mode. This will only be available if your nodes are all on the same version.

When you first put JIRA into upgrade mode, you have the option to cancel the upgrade, which will take JIRA out of upgrade mode. This is available until you start upgrading your nodes. Once you've upgraded your nodes to the same version, you can finalize the upgrade. To cancel the upgrade, you'd need to roll each node back to it's original version.

2. Upgrade your nodes

Once your JIRA instance is in upgrade mode, you can upgrade each node individually. Upgrading a node will involve stopping JIRA, upgrading the installation, and then starting JIRA. Stopping JIRA will remove the node from your cluster, making it unavailable, and any users logged in to that node will lose their current session, before being routed to another node. As the administrator, it's up to you to decide which nodes to upgrade and in which order. You always need to have at least one node online and connected to your cluster to achieve zero downtime. There's some useful information on monitoring a JIRA Data Center node here, and depending on your setup, you may be able to 'drain' your nodes to minimise impact.

The JIRA Software installer automatically performs most of the upgrade tasks for you. However, if you have made customizations to your JIRA installation, you will need to migrate the customized files manually to the upgraded installation. This step takes place during the upgrade of your node.

You're now ready to upgrade your nodes. Make sure you can access the installer before you start, and select the node you need to upgrade:

  I'm upgrading a Windows environment
  1. Shut down your JIRA application.
  2. Run the installer '.exe' file to start the upgrade wizard.
    (info) If a Windows 7 (or Vista) 'User Account Control' dialog box asks you to allow the upgrade wizard to make changes to your computer, specify Yes. If you do not, the installation wizard will have restricted access to your operating system and any subsequent installation options will be limited.
  3. At the 'Upgrading JIRA?' step, choose the Upgrade an existing JIRA installation option.
  4. In the Existing JIRA installation directory field, specify the JIRA application installation directory of your JIRA installation to be upgraded.
    (info) The upgrade wizard will attempt to find an existing JIRA installation and use its location to pre-populate this field. However, always verify this location, particularly if you have multiple JIRA installations running on the same machine.
  5. During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following options:
    1. At the 'Back up JIRA directories' step, ensure the Back up these directories option is selected. This creates 'zip' archive file backups of your existing JIRA installation and JIRA home directories in their respective parent directory locations.
      (info)Please Note:
      • Choosing this option is strongly recommended!
      • At this point, the upgrade wizard notes any customizations in your existing JIRA installation directory which it cannot automatically migrate to your upgraded JIRA installation. If you are informed of any files containing such customizations, please make a note of these files as you will need to manually migrate these customizations.
  6. At the last step of the upgrade wizard, select the option to launch the upgraded JIRA installation in a browser so you can check the upgrade.
  I'm upgrading a Linux environment

Upgrading JIRA on Linux

  1. Download the appropriate 'JIRA 'Linux 64-bit / 32-bit Installer' (.bin) file that suits your operating system (for the new version of JIRA) from the JIRA Download page.
  2. Shut down JIRA.
  3. Open a Linux console and change directory (cd) to the '.bin' file's directory.
    (warning) If the '.bin' file is not executable after downloading it, make it executable, for example:
    chmod a+x atlassian-jira-X.Y.bin 
    (where X.Y represents your version of JIRA)
  4. Execute the '.bin' file to start the upgrade wizard.
  5. When prompted to choose between creating a new JIRA installation or upgrading an existing installation, choose the Upgrade an existing JIRA installation option.
  6. Specify the JIRA installation directory of your JIRA installation to be upgraded.
    (info) The upgrade wizard will attempt to find an existing JIRA installation and will provide its location as a choice. However, always verify this location, particularly if you have multiple JIRA installations running on the same machine.
  7. During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following options:
    1. Choose the option to back up JIRA's directories. This creates 'zip' archive file backups of your existing JIRA installation and JIRA home directories in their respective parent directory locations.
      (info)Please Note:
      • Choosing this option is strongly recommended!
      • At this point, the upgrade wizard notes any customizations in your existing JIRA installation directory which it cannot automatically migrate to your upgraded JIRA installation. If you are informed of any files containing such customizations, please make a note of these files as you will need to manually migrate these customizations.
    2. After the 'Upgrade Check List' step, the existing JIRA installation will be shut down if it is still running. The upgrade wizard will then:
      1. Back up your existing JIRA installation.
      2. Delete the contents of the existing JIRA installation directory.
      3. Install the new version of JIRA to the existing JIRA installation directory.
      4. Starts your new (upgraded) JIRA installation.
        (warning) If you noted any files that contain customizations which must be migrated manually to your upgraded JIRA installation, then:
        1. Stop the upgraded JIRA installation.
        2. Migrate the customizations from these files into the upgraded JIRA application installation directory.

            Migrating customizations

          If you have modified properties in configuration files of your existing JIRA installation, make the same modifications in your new JIRA installation. However, because the properties in the configuration files may have changed between versions, you cannot simply copy the configuration files from your existing installation and replace the equivalent files in the new installation.

          For each file you have modified in your existing JIRA installation, you need to manually edit each equivalent file in your new JIRA installation and re-apply your modifications. If a file is not present in your new JIRA installation (for example, osuser.xml in recent JIRA versions), then copy that file over to your new JIRA installation.

          The table below lists the most commonly modified files and their locations within your JIRA Installation Directory:

          File

          Location in 'recommended' (formerly 'Standalone') JIRA distributions

          Description

          jira-application.properties

          atlassian-jira/WEB-INF/classes

          Upon starting your new JIRA installation, any custom property values in the jira-application.properties file will automatically be migrated across to either the JIRA database or jira-config.properties file. jira.home is the only property of the jira-application.properties file subsequently used by JIRA.

          setenv.bat (Windows) or setenv.sh (Linux)

          bin

          Increasing JIRA application memory

          osuser.xml
          (not required if upgrading from JIRA 4.3.0 or later)

          atlassian-jira/WEB-INF/classes

          Modified if you have integrated LDAP with JIRAintegrated Crowd with JIRA, or if you are using a custom form of external user management or user authentication.

          seraph-config.xml

          atlassian-jira/WEB-INF/classes

          Modified if you have integrated Crowd with JIRA.

          server.xml

          conf

          Modified in the following situations:

          (tick) The version-specific upgrade notes contain details on properties which may have changed in these commonly modified files.

          In addition to the files above, you should also consider and/or perform the following configurations as part of the upgrade process:

          • Using JIRA with Atlassian's Crowd? — If you are using Crowd with JIRA, configure your new JIRA to talk to Crowd as described in integrated Crowd with JIRA.
            • Remember to configure Crowd to grant JIRA's new hostname/IP access.
          • Allocating additional memory to JIRA — If you had previously allocated additional memory to JIRA, do the same for your new JIRA instance. For more information refer to Increasing JIRA application memory.
          • Character encoding — Ensure that character encoding (i.e. locale) is the same on the new and old locations. Your new version of JIRA may not function correctly if attachments are moved between two system with incompatible encoding.
          • Customizations — If you had made any customizations (code, templates or configuration files), copy over compatible versions of these changes to the new JIRA. (The developers within your organization who made the customizations to your old version will need to build and test equivalent changes for the new version, and provide you with the files to copy to your upgraded JIRA installation.)
          • (Optional) Running JIRA on a different port — If your new JIRA is installed on the same machine as your old JIRA, you may wish to make sure it runs on a different port (in case you ever need to restart your old JIRA). See Changing JIRA's TCP ports for details.
        3. Restart the upgraded JIRA installation. This will automatically add it back to your cluster.

  8. The last step of the upgrade wizard provides you with a link to launch the upgraded JIRA installation in a browser, so you can check the upgrade.

When you've upgraded your first node, check that it's available on your cluster, and that users are able to log in and use the node. Once you've done this, repeat the process for each node.

Once you've upgraded all your nodes to the latest version, when you check your JIRA upgrades page (> Applications > JIRA upgrades) you will have the option to finalize your upgrade. If you haven't upgraded all the nodes, the Finalize upgrade button won't be available, and you'll need to check which node/s still require upgrading. You can finalize your update when all nodes are upgraded.

3. Finalize your upgrade

Finalizing an upgrade will allow any required upgrade tasks to run on your instance, and take JIRA out of upgrade mode. Once the required tasks have completed, you're installation is upgraded.

  1. Navigate to > Applications > JIRA upgrades.
  2. Click Finalize upgrade. This will only be available if all your nodes are all on the same, new version.

Congratulations! You've upgraded your instance and achieved zero downtime! 

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport