Using the latest version?
JFrog Platform User Guide
JFrog Artifactory 6.x Documentation
To get the latest version, go to the JFrog Unified Platform
Home Directory
When setting up Artifactory HA you need to configure the $ARTIFACTORY_HOME
directory separately for each of the Artifactory cluster nodes in your system.
The general layout of these directories is as follows:
Installing Artifactory HA
An Artifactory HA node is first installed as an Artifactory Pro instance, and is then modified to operate as a node in the HA cluster by configuring the $ARTIFACTORY_HOME/etc/ha-node.properties
file.
The Installation Process
The binary storage in an HA installation must be accessible to all nodes in the cluster. This is achieved either by mounting a Network File System (NFS) on each cluster node, using shared object storage, or by using the nodes' local file systems while using a mechanism that synchronizes the binaries between them.
The installation procedure involves two stages:
- Setting up your storage configuration
The storage configuration varies depending on your decision for two parameters of your setup:- Binary store: Do you plan to use Filesystem Storage to store binaries on your nodes' filesystems, or a Cloud Storage provider such as S3, GCS or any other S3-compliant provider?
- NFS: Do you plan to use the Network File System (NFS) or not?
- Installing the cluster nodes
Once your storage is configured and set up, the rest of the installation process is identical
Setting Up Your Storage Configuration
Your choice for binary store and use of NFS or not leads to one of the following four options for setting up your storage configuration:
Using Filesystem Storage with the NFS
Using Filesystem Storage Without the NFS
Using Cloud Storage With the NFS
Using Cloud Storage Without the NFS
Installing the Cluster Nodes
Once you have completed setting up your filestore configuration, the process for installing the cluster nodes is identical and described in the steps below:
- Install the primary node
- Create the Master Key
- Add licenses
- Set the cluster's URL Base
- Add secondary nodes
Installing the Primary Node
Go through a regular installation of Artifactory Pro as described in Installing Artifactory, and then convert it to be the HA primary node by adding the ha-node.properties
file you created when you set up your storage configuration to the $ARTIFACTORY_HOME/etc. Do not start up the instance yet.
Note that an external database must be configured for usage at this point, as mentioned in the Requirements section
You should also verify that your database JDBC driver is correctly located in $ARTIFACTORY_HOME/tomcat/lib for each Artifactory cluster node.
Create the Master Key
The Master key is an AES 128 bit secret key that's used by Artifactory to securely synchronize files between cluster nodes. It is responsible to encrypt and decrypt the shared data in the database.
By default the master.key
file is automatically generated by Artifactory during the initial start up of the primary node. Optionally, you can generate one manually by running ‘openssl rand -hex 16
’, which will output a 128 bit key size (hexadecimal encoded). Place this key in the $ARTIFACTORY_HOME/etc/security/master.key directory, before starting the primary node.
Add Licenses
There are several ways you can add licenses to the cluster:
- Using the Cluster License Manager UI or REST API as described in Adding Licenses
- As part of the onboarding wizard you will get when you start up Artifactory for the first time
- Using the Artifactory Bootstrap YAML File (NOTE: this will only work for the primary node)
Since currently, the only operative node is the primary node, you can install your licenses there. Once you add the secondary nodes to the cluster, they will be licensed automatically through the Cluster License Manager.
All licenses used must be Enterprise licenses.
Set the URL Base
After you have installed the node and verified that your system is working correctly as an HA installation, you should configure the Custom URL Base.
In the Admin tab under Configuration | General Configuration, set the Custom Base URL field to the URL of the Load Balancer.
Add Secondary Nodes
You should also verify that your database JDBC driver is correctly located in $ARTIFACTORY_HOME/tomcat/lib for each Artifactory cluster node.
To add secondary nodes, for each node, follow these steps:
- Create an
ha-node.properties
file according to how you want to set up your storage configuration. - Go through a new Artifactory Pro installation as described in Installing Artifactory. Do not start up the instance yet.
Note that an external database must be configured for usage at this point, as mentioned in the Requirements section Once the Artifactory Pro installation is complete, add the
ha-node.properties
file you created to the$ARTIFACTORY_HOME/etc
folder.On the secondary node, create an $ARTIFACTORY_HOME/etc/security folder, and copy to it the Master Key file ($ARTIFACTORY_HOME/etc/security/master.key) from one of the existing nodes in the cluster.
Warning: Master Key and db.properties
This is a critical step in the installation process. The Master Key and db.properties files must be installed in each secondary node before you start it up for it to operate correctly in the cluster.Start up the cluster node. Upon starting up, the node is automatically allocated a license by the Cluster License Manager.
Warning: Setting Enterprise+ Service Licensing in an HA Environment
For Enterprise+ installations, licenses are added in JFrog Mission Control during the Add New Service process. When adding a new service, the license is extracted from the license bucket.
During an HA installation, if you are adding a new node or swapping an existing one, you need to manually reconfigure the services with the licenses.- Test your HA configuration after each cluster node that you add to your system.
Warning: Ensure network communication
Make sure that network communication is enabled between the cluster nodes for each of the following:
- context.url
hazelcast.interface and membership.port (used together. For example,
172.24.0.1:10001)
membership.port not used from version 6.2.0
From version 6.2.0 this parameter should be set to 0 since an internal locking mechanism was introduced in Artifactory removing the need for it. Since the membership.port is no longer used by Artifactory you can also consider removing this parameter completely from the ha-node.properties file starting from version 6.2.0
For more details please refer to the JFrog Knowledge Base.
Note: Synchronizing configuration files between nodes in an HA cluster
From version 5.0, Artifactory automatically propagates configuration files between the nodes of an HA cluster. These include both internal configuration files as well as binarystore.xml
(which is responsible for the Artifactory filestore configuration), and the artifactory.system.properties
file which may be modified by an Artifactory administrator.
Note that to modify the binarystore.xml
or artifactory.system.properties
you must make the changes on the primary node and then restart your HA cluster for the changes to take effect.
In addition, from version 5.7.0, propagation of configuration files ignores the timestamp of the files on each corresponding node and makes sure to mirror those on the primary node.
Database Locking
From version 6.0.0, the new database locking mechanism adds its own connection pool (defaults to the value of the pool.max.active value).
However, you may need to adjust your database connection limit to accept more connections. For example, if your database is set to accept up to 100 connections from each node, you may consider increasing the limit to 200 concurrent connections per-node, to accommodate the full utilization of the locking connection pool. Your database should accept the number of configured connections per-node multiplied by the number of the nodes in the cluster.
Session Management
From version 6.2, Artifactory offers different alternatives for session management between the Artifactory HA members when accessing one of the members.
The way to manage sessions is controlled via the artifactory.map.provider.type
property (in the $ARTIFACTORY_HOME/etc/artifactory.system.properties
file) which can take the following values:
db | (default) Sessions are managed by the database |
distributed | Sessions are managed by Hazelcast |
jvm | Sessions are managed by the JVM |
If sessions are configured to be managed by the database, Artifactory will also schedule a cron job to cleanup old sessions.
The cron expression to trigger the sessions can be configured using the artifactory.db.session.cleanup.cron
property in the $ARTIFACTORY_HOME/etc/artifactory.system.properties
file.
During installation, this cron expression is set with a default value that triggers the cleanup at a set minute (determined randomly) past each hour.
Upgrading Artifactory HA
Upgrading Artifactory HA depends on which version you are starting from. For detailed instructions, please refer to Upgrading an Enterprise HA Cluster.
Testing Your HA Configuration
The following are a series of tests you can do to verify that your system is configured correctly as an HA installation:
- 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 license. 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.
Cluster License Management
Artifactory 5.0 introduces an automated license management interface for HA clusters through which all licenses are allocated automatically to nodes as they are added to the cluster. A batch of licenses can be added through the UI and REST API to any node in a cluster.
A new node starting up will request an available license from the pool automatically, and will be allocated the license with the latest expiry date. The license is also automatically returned to the pool if the node is shut down or removed from the HA cluster.
Which license is allocated?
Note that adding a license through a node does not necessarily mean that the license will be attached to that specific node. The license is added to the pool available and the available license with the latest expiry date will be allocated to the node.
Once you have purchased a set of licenses, they are provided to you as a space-separated or newline-separated list.
Adding Licenses
There are three ways that licenses can be added to an HA cluster:
- Through the UI
- Using the REST API
- Adding them to the primary node's filesystem (for automation).
Specifying multiple licenses
When specifying multiple licenses, whether in the Artifactory UI, using the REST API or in the artifactory.cluster.license
file, make sure that the licenses are separated by a newline.
Using the UI
Through the UI, in the Admin module, under Configuration | Artifactory Licenses, you can view all licenses uploaded to your cluster.
To add licenses to your cluster, click New and copy your license key(s) into the License Key entry field. You can also simply drag and drop the file containing the license key(s) into the same field. Make sure that each license is separated by a newline.
Using the REST API
You can also add licenses through the Install License REST API endpoint
Using the Primary Node's Filesystem
To accommodate spinning up Artifactory HA nodes using automation, before booting up your primary node, you can place the artifactory.cluster.license
file in its $ARTIFACTORY_HOME/etc
folder. Upon being booted up, the primary node automatically extracts one of the licenses.
Similarly, upon being started up, each secondary node also automatically extracts one of the remaining available licenses.
License Expiry
Nodes running with a license that is about to expire will automatically be updated with a new license available from the pool. Artifactory administrators can manually delete the expired license from within the UI or using REST API.
Deleting Licenses
A license can be deleted under one the following conditions:
- It is not currently being used,
- There is an alternative license available in the pool. In this case, the node to which the deleted license was attached will automatically be allocated with an alternative license.
Perpetual License
Note that Artifactory licenses are perpetual and may continue to activate an Artifactory instance indefinitely, however, an instance running on an expired license may not be upgraded and is not eligible for support.
REST API
You can manage your Artifactory HA licenses using the HA License Information, Install HA Cluster Licenses and Delete HA Cluster License REST API endpoints.