Overview

This page describes the process to upgrade your Artifactory Enterprise HA cluster.

No down time

Since your cluster contains more than one node, you may complete the upgrade process without incurring any down time to the Artifactory service your organization is using.

Before You Begin

  1. Backup your system: As a precaution, before you begin the upgrade process, we strongly recommend performing a complete Complete System Backup
  2. Backup your database
  3. Read through the process: The backup procedure may vary slightly depending on your current version and your installation type (ZIP, RPM, Debian or Docker). To familiarize yourself with the specific backup process that you should use, we recommend reading through all the steps of the process before you begin

In version 5.5, Artifactory's database underwent a schema change to accommodate SHA256 checksums. As a result, when upgrading from version 5.4.5 and below to version 5.5 and above, you need to follow one of the options described in the detailed instructions below.  

 


The Upgrade Process

Upgrading Artifactory HA depends on which version you are starting from. Read the sections below carefully to make sure you complete the process correctly. 

Upgrading From Versions Below 5.4.6

Artifactory 5.5 implements a database schema change to support SHA-256 checksums. If your current version is 5.4.6, you may proceed with the normal upgrade procedure described in Upgrading Steps below.

If your current version is below 5.4.6, to accommodate this change, you may select one of the following two upgrade options:

  1. Two-phase, zero downtime
    In this option, you first need to upgrade your HA cluster to version 5.4.6. Once this upgrade is completed, you can then proceed to upgrade your HA cluster to version 5.5 and above. In both phases, you follow the normal upgrade procedure described in in Upgrading Steps below.
  2. One phase with downtime
    In this upgrade option, your HA cluster will be down until you complete the upgrade for all nodes. This option requires you to execute the following preprocessing: 
    • While the primary and all secondary nodes are up and running, add the following flag to artifactory.system.properties on the primary node:

      artifactory.upgrade.allowAnyUpgrade.forVersion=<to_version>
      For example:
      artifactory.upgrade.allowAnyUpgrade.forVersion=5.5.0
    • Wait until this property is synchronized to the database. You can verify that it has been synchronized by checking the artifactory.log file in each of the secondary nodes. Your nodes should display a message that looks like this:

      [Node ID: some_node_id] detected remote modify for config 'artifactory.system.properties'

    • Now you can proceed with the normal upgrade procedure described in in Upgrading Steps below.

      Normally, upgrading an enterprise HA cluster does not incur downtime. As you upgrade each node, the other nodes continue to provide service.

      In this particular scenario of upgrading from version 5.4.5 and below to version 5.5 and above in a single phase, once you upgrade your primary node, your cluster will be in an incoherent state and will not be able to provide service until all nodes in the cluster have been upgraded. You can expect to see many errors in the log file until the upgrade is complete.

      As a result, we recommend completely taking down the whole cluster (i.e. taking down all cluster nodes), and then following the upgrade procedure, bringing up each node as it is upgraded.

If you try upgrading directly to version 5.5 and above without following one of these options, the upgrade will fail and the following message will be logged in the artifactory.log file:
To upgrade your HA installation to this version, you first need to upgrade to version 5.4.6 which implements changes required to accommodate a database schema change.

Continue to recovering from an Attempt to Upgrade Directly to Version 5.5 and Above

 

Upgrading Steps

Upgrading to the latest version is conducted in three phases:
  1. Upgrading the primary node
  2. Upgrading the secondary nodes
  3. Verifying the HA installation and configuration

If you want to stop using a shared NFS once the upgrade procedure is complete (this is optional), please refer to Migrating Data from NFS to migrate to alternative storage.

Upgrading the Primary Node

  1. Remove the primary node from the load balancer, so all requests are directed to the secondary nodes. You may look at  $ARTIFACTORY_NODE_HOME/logs/request.log and ARTIFACTORY_URL/api/tasks (search for "running") to ensure that Artifactory is completely inactive.
  2. Perform a graceful shutdown of the primary node. While the primary node is down, the load balancer should redirect all queries to the secondary nodes.
  3. Continue with the upgrade according to the instructions for your installation type.

     If your current version is 3.5 or higher, you first need to upgrade to the latest version 4.x using the procedure in this link and then upgrade to 5.x.

    Upgrading Artifactory HA from a version below 3.5 to version 5.x directly is not supported. To upgrade to version 5.x, you first need to upgrade your system to v3.5+, and then upgrade again to the final version 4.x, and then finally to 5.x.

  4. Start up the primary node. When the primary node starts up, it will recognize that the HA cluster nodes are not all running the same version of Artifactory, and consequently, the system will be limited to allowing uploads and downloads. 

    Any attempt to perform other actions such as changing the DB schema, modifying permissions, changing repository configuration and more, are strictly blocked. This limitation will continue until all the cluster nodes are once again running the same version.

    Running the HA cluster nodes with different versions generates exceptions. These can be seen in the log files and reflect the temporary inconsistent state during the upgrade process. This is normal and should be ignored until all the cluster nodes are, once again, running the same version.

  5. Put the primary node back to the load balancer.

Upgrading the Secondary Node

For each secondary node in your HA cluster, perform the following steps:

  1. Remove the node from the load balancer, so all requests are directed to the other nodes. You may look at  $ARTIFACTORY_NODE_HOME/logs/request.log and ARTIFACTORY_URL/api/tasks (search for "running") to ensure that Artifactory is completely inactive.
  2. Perform a graceful shutdown of the node. While the node is down, the load balancer should redirect all queries to the other nodes.

  3. Continue with the upgrade according to the instructions for your installation type.

    If your current version is 3.5 or higher, you first need to upgrade to the latest version 4.x using the following procedure and then upgrade to 5.x.

    Upgrading Artifactory HA from a version below 3.5 to version 5.x directly is not supported. To upgrade to version 5.x, you first need to upgrade your system to v3.5+, and then upgrade again to the final version 4.x, and then finally to 5.x.

  4. Complete this step only when upgrading from 5.4.5 and below to 5.7 and above with 'One phase with downtime'
    Copy the Master Key from the primary node located under the $ARTIFACTORY_HOME/etc/security/master.key directory, to the secondary node under the $ARTIFACTORY_HOME/etc/security/master.key directory.
  5. Start up the secondary node.
  6. Add the secondary node back to the load balancer.
  7. Repeat this process for each secondary node.

     

 After starting up each secondary node, we recommend inspecting the ha-node.properties, db.properties and binarystore.xml files (under $ARTIFACTORY_NODE_HOME/etc) to ensure they are correctly configured 

Verify the HA Installation and Configuration

Once you have completed upgrading your HA cluster, you can verify that your cluster has been installed and configured correctly use the following series of tests:

 

If you want to stop using a shared NFS once the upgrade procedure is complete (this is optional), please refer to Migrating Data from NFS to migrate to alternative storage.


Troubleshooting

Recovering from an Attempt to Upgrade Directly to Version 5.5 and Above

If you try to upgrade from version 5.4.5 and below to version 5.5 and above without following the procedure in one of the two options above, the upgrade will fail with the following message:

To upgrade your HA installation to this version, you first need to upgrade to version 5.4.6 which implements changes required to accommodate a database schema change.

Depending on your installation type, the message may be displayed in the artifactory.log file, the $ARTIFACTORY_HOME/tomcat/logs/localhost.log file or in the command line output.

To recover from this error and, you first need to replace your current version as described below (according to your installation type).

Then you can proceed with upgrading to version 5.4.6 as required using the normal upgrade procedure, and then on to your final desired version, also, using the normal upgrade procedure.

Reinstalling Your Current Version

Reinstalling is similar to the process you went through when upgrading to your current version according to your installatian type.

For example, if you tried to upgrade from version 5.2 directly to version 5.5, you now need to reinstall version 5.2 and follow the instructions below, according to your installation type.

 Zip Installation

Follow the upgrade instructions for a Zip installation using your current version.  

Debian Installation

Follow the upgrade instructions for a Debian installation using your current version.  

If your current version is below 5.4.0, make sure to remove the $ARTIFACTORY_HOME/tomcat/webapps/access folder. This folder is a remnant of the failed attempt to upgrade to version 5.5 and is not needed in versions previous to 5.4 where the Access Service is bundled together with the Artifactory WAR. 

Docker Installation

Follow the upgrade instructions for a Docker installation using your current version.  

RPM Installation 

Follow the upgrade instructions for an RPM installation using your current version. 

If your current version is below 5.4.0, make sure to remove the $ARTIFACTORY_HOME/tomcat/webapps/access folder. This folder is a remnant of the failed attempt to upgrade to version 5.5 and is not needed in versions previous to 5.4 where the Access Service is bundled together with the Artifactory WAR.