Using Artifactory 6.x ?
JFrog Artifactory 6.x User Guide
Have a question? Want to report an issue? Contact JFrog support
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
Upgrading Steps
- Upgrading the primary node
- Upgrading the secondary nodes
- Verifying the HA installation and configuration
Want to stop using NFS?
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
- 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.
- 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.
Continue with the upgrade according to the instructions for your installation type.
Upgrading from 3.x?
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.
ZIP Installation
Debian Installation
Docker Installation
RPM Installation
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.
Version inconsistency generates exceptions
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.
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:
- 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.
Perform a graceful shutdown of the node. While the node is down, the load balancer should redirect all queries to the other nodes.
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.
ZIP Installation
Debian Installation
Docker Installation
RPM Installation
- 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. - Start up the secondary node.
- Add the secondary node back to the load balancer.
Repeat this process for each secondary node.
Check your installation
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:
- Directly Access the Artifactory UI for the server you have just configured
- In the Admin module go to Advanced | System Logs to view the log and verify that you see an entry for HA Node ID.
- The bottom of the module navigation bar should also indicate that you are running with an Enterprise licens. In case of an error you will see an error message in the page header.
- Access Artifactory through your load balancer and log in as Admin.
In the Admin module go to Configuration. There should be a section called High Availability. When selected you should see a table with details on all the Artifactory nodes in your cluster as displayed below.
In the Admin module under Configuration | General, verify that the Custom URL Base field is correctly configured to the URL of the Load Balancer.
Want to stop using NFS?
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.