Overview

The procedure to upgrade Xray depends on your installation type. We strongly recommend reading through this page before proceeding with your upgrade.

Before you upgrade Xray please refer to additional information on system requirements (for storage, databases, browsers and other requirements), and the system architecture.

There are several new concepts introduced in Xray 3.x, improving the installation and customization process.

Note: Make sure to use the same upgrade method (RPM, Debian, Docker, etc.) as the one you initially used to install Xray.

Remember that when using the PostgreSQL command below to only use the version you running.

It is recommended that you first review what's new with the latest JFrog Platform. Review the breaking changes, deprecated features and more.

To ensure you can restore your Xray and database in case you encounter any issues during the upgrade process, we strongly recommend you make sure your system and database backups are up to date.

From version 3.x, MongoDB will not be used by Xray except during the initial migration phase from version 2.x. The data will be automatically migrated from MongoDB to PostgreSQL. Make sure your PostgreSQL storage size is increased by at least 2.5 times than its current size.

When upgrading to the JFrog Platform, Xray must be connected only to a single Artifactory instance. If you have one Xray instance connected to more than one Artifactory instances, use one of the following options before proceeding with any upgrade: 

Option 1 (recommended): Keep one connected Artifactory instance to your single Xray instance, and upgrade the rest to version 7.x with newly installed Xray version 3.x instances. This option will require re-indexing the the additional Artifactory instances, and will cause some loss of configuration data. Learn More >

Option 2: Install additional Xray version 2.x instances for each Artifactory instance that you have, and restore all MongoDB and PostgreSQL data. Continue to upgrade each Artifactory and Xray pairs to version 7.x and version 3.x. This procedure is only suggested if you must keep all your Xray configurations and easily reconfigure them in the new instances. Learn More >

Xray 3.x and 2.x support PostgreSQL versions 9.5, 9.6, 10, 11, 12 (the earliest version of Xray 2.x that supports PostgreSQL 10-12 is Xray 2.16). Because PostgreSQL is ending its support for some of its older versions, including 9.5 in February 2021 and 9.6 in November 2021. Although it is possible to upgrade incrementally from 9.5 to 9.6, JFrog recommends upgrading to PostgreSQL 12. This will extend the time until the next PostgreSQL end of support and enables Xray to take advantage of the latest abilities provided by the new versions, such as better performance, etc

To learn about the process and requirements for upgrading PostgreSQL, see JFrog Xray PostgreSQL Upgrade - PostgreSQL 9.x EoS.


Upgrade Steps

The upgrade procedure involves the following steps:

  1. Download Xray (Docker Compose, RPM, Debian).
  2. Stop the Xray service
  3. Install Xray according to the distribution type.
  4. Check the Migration Log and review system.yaml to validate the migration was successful (only for upgrading from v3.x).
  5. Start the service using the start scripts or OS service management.
  6. Check the Xray Log for the status of the service.

The default Xray home directory is defined according to the installation type. For additional details see the Product Directory Structure page.

Note: This guide uses $JFROG_HOME to represent the JFrog root directory containing the deployed product.

Upgrading from Version Below 2.7

To upgrade from version 2.6 and below, you first need to upgrade to version 2.7.x as described in the Upgrading Xray 2 documentation, and then continue to upgrade from version 2.7 to 3.x.

From version 3.x, the MongoDB is not used by Xray, except during the initial migration phase from version 2.x. The data is automatically migrated from MongoDB to PostgreSQL from version 2.7x and above. After upgrading to version 2.7x, you must ensure that all data migrations are complete before proceeding to upgrade to version 3.x. The xray-migration-readiness tool enables you to verify that all data migrations are complete. Download the tool, and follow the instructions in the readme file.

Upgrading from Version 2.7 to 3.x

JFrog Xray v3.x is only compatible with JFrog Artifactory v7.x. To upgrade, you must first install JFrog Artifactory 7.x.

The following upgrade methods are supported:

Interactive Script Upgrade (recommended)

The installer script works with all supported upgrade methods (RPM, Debian and Docker Compose). It provides you an interactive way to upgrade Xray and its dependencies.

  1. Download Xray (RPM, Debian or Docker Compose).

  2. Stop the service.

    xray stop
docker ps -a --format '{{.Names}}' | grep ^xray_* | xargs docker rm -f
    cd /opt/jfrog/xray/scripts
./xray.sh stop

  3. Extract the contents of the compressed archive and go to the extracted folder. The installer script is located in the extracted folder.

    tar -xvf jfrog-xray-<version>-<compose|rpm|deb>.tar.gz
cd jfrog-xray-<version>-<compose|rpm|deb>

    This .env file is used by docker-compose and is updated during installations and upgrades.

    Notice that some operating systems do not display dot files by default. If you make any changes to the file, remember to backup before an upgrade.

  4. For non Docker-Compose installations, make sure your MongoDB is running, to ensure that the migration process to PostgreSQL will work.
    For Docker-Compose installations, MongoDB services will come up as part of the new compose files. 

  5. Run the installer script.
    Note: the script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.

    ./config.sh

    A .env file is included within the archive. This file is used by docker-compose and is updated during installations and upgrades.

    Some Operating Systems do not display dot files by default so please be aware of this file.

    If you make changes to the file, remember to backup before an upgrade

    ./install.sh
  6. Check that the configurations migration has completed successfully, by reviewing the following files:

    1. migration log: $JFROG_HOME/xray/var/log/migration.log file

    2. system.yaml configuration: $JFROG_HOME/xray/var/etc/system.yaml
      This newly created file will contain your current custom configurations in the new format.

      Please ensure that a large file handle limit is specified before you start Xray. 

  7. Start the Xray service.

    systemctl start xray.service

    Starting from Xray 3.8x the stop and restart action on Xray will not be applied to RabbitMQ process. On start action of Xray, if RabbitMQ is not running , it will be started.

    If you want the script to perform stop and restart action on RabbitMQ, set shared.rabbitMq.autoStop as true in the system.yaml. Note that this flag is not consumed in docker-compose installation.

    systemctl start xray
    cd jfrog-xray-<version>-compose

# Starting from Xray 3.8x RabbitMQ has been moved to a compose file of its own, this needs to be started before starting other services
docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml up -d

# Starting from Xray 3.8.x, PostgreSQL needs to be started before starting the other services.
docker-compose -p xray-postgres -f docker-compose-postgres-9-5-2v.yaml up -d

docker-compose -p xray up -d

docker-compose -p xray ps
docker-compose -p xray down
  8. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.

  9. Check Xray Log.

    tail -f $JFROG_HOME/var/log/console.log

After the migration is successfully ended, it is recommended to complete the following steps:

  1. Validate that your Xray data has migrated successfully.
  2. Remove MongoDB configuration from the system.yaml.
  3. For RPM installations, uninstall the MongoDB database.
    For Docker-Compose installations, you either need to remove the "mongodb" service from the docker-compose.yml files, or run the installation script again, the script will determine that MongoDB is no longer necessary and will do this automatically.


Manual RPM Upgrade

The RPM upgrade bundles Xray and all its dependencies. It is provided as native RPM packages, where Xray and its dependencies must be installed separately. Use this, if you are automating installations.

  1. Download Xray (RPM).

  2. Stop the current service.

    cd /opt/jfrog/xray/scripts
./xray.sh stop

  3. Extract the contents of the compressed archive and go to the extracted folder.

    tar -xvf jfrog-xray-<version>-rpm.tar.gz
cd jfrog-xray-<version>-rpm
  4. Make sure your MongoDB is running, to ensure that the migration process to PostgreSQL will work.

  5. Install Xray as a service on Red Hat compatible Linux distributions, as a root user.

    yum -y install ./xray/xray.rpm

  6. Check that the migration has completed successfully, by reviewing the following files:

    1. migration log: $JFROG_HOME/xray/var/log/migration.log file

    2. system.yaml configuration: $JFROG_HOME/xray/var/etc/system.yaml
      This newly created file will contain your current custom configurations in the new format.

      Please ensure that a large file handle limit is specified before you start Xray. 

  7. Set the Artifactory connection details.

  8. Make sure the third party services are running.

    If you had the PostgreSQL database that was packaged as part of 2.x installed, the same will be used in the current installation. It can be managed using the following commands:

    service postgresql-9.5 start|stop|status

    From version 3.x, RabbitMQ is packaged and managed as part of the Xray RPM. Any action (stop, start and status) on the main service of Xray will be performed on RabbitMQ as well. The existing RabbitMQ RPM which was installed as part of 2.x can be uninstalled after Xray 3.x is successfully installed and running.

    From version 3.x, MongoDB will not be used by Xray except during the migration phase. On start of version 3.x, data will be automatically migrated from MongoDB to PostgreSQL. Make sure both the databases are up and running before Xray services are started. During the migration, Xray will not be accessible. The migration duration will depend on the data size to be migrated.

    service mongod start|stop|status

  9. Start Xray.

    systemctl start xray.service
    systemctl start xray

  10. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.

  11. Check Xray Log.

    tail -f $JFROG_HOME/xray/var/log/console.log

After the migration is successfully ended, it is recommended to complete the following steps:

  1. Validate that your Xray data has migrated successfully.
  2. Remove MongoDB configuration from the system.yaml.
  3. Uninstall the MongoDB database.


Manual Debian Upgrade

The Debian upgrade bundles Xray and all its dependencies. It is provided as native Debian packages, where Xray and its dependencies must be installed separately. Use this, if you are automating installations.

  1. Download Xray (Debian).

  2. Stop the current server.

    cd /opt/jfrog/xray/scripts
./xray.sh stop

  3. Extract the contents of the compressed archive and go to the extracted folder.

    tar -xvf jfrog-xray-<version>-deb.tar.gz
cd jfrog-xray-<version>-deb
  4. Make sure your MongoDB is running, to ensure that the migration process to PostgreSQL will work.

  5. Install Xray as a service on a Debian compatible Linux distributions, as a root user.

    dpkg -i ./xray/xray.deb

  6. Check that the migration has completed successfully, by reviewing the following files:

    1. migration log: $JFROG_HOME/xray/var/log/migration.log file

    2. system.yaml configuration: $JFROG_HOME/xray/var/etc/system.yaml
      This newly created file will contain your current custom configurations in the new format.

      Please ensure that a large file handle limit is specified before you start Xray. 

  7. Set the Artifactory connection details.

  8. Make sure the third party services are running.

    If you had the PostgreSQL database that was packaged as part of 2.x installed, the same will be used in the current installation. It can be managed using the following commands:

    service postgresql-9.5 start|stop|status

    From 3.x, RabbitMQ is packaged and managed as part of the Xray DEB. Any action (stop, start and status) on the main service of Xray will be performed on RabbitMQ as well. The existing RabbitMQ DEB which was installed as part of 2.x can be uninstalled after Xray 3.x is successfully installed and running.

    From 3.x, MongoDB will not be used by Xray. On start of 3.x, data will be migrated from MongoDB to PostgreSQL. Make sure both the databases are up and running before Xray services are started. This can be uninstalled after Xray 3.x is successfully installed and running.

    service mongod start|stop|status

  9. Start Xray.

    systemctl start xray.service
    systemctl start xray
  10. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.

  11. Check Xray Log.

    tail -f $JFROG_HOME/xray/var/log/console.log

After the migration is successfully ended, it is recommended to complete the following steps:

  1. Validate that your Xray data has migrated successfully.
  2. Remove MongoDB configuration from the system.yaml.
  3. Uninstall the MongoDB database.

HA Upgrade

This section describes the process to upgrade your Xray High Availability cluster.

The Xray load balancer is no longer required when upgrading an Xray HA cluster from version 2.x to 3.x as all the Xray requests are now routed through the Platform Router in the JFrog Platform.

The following installation methods are supported:

Docker Compose

Perform the following steps for each node in your system. When starting up each node, make sure to enter the correct details according to first node or additional node being added to the cluster.

The instructions below assume that you are upgrading from a 2.X official Docker installation.

  1. Stop all the cluster nodes that are setup using HA by running the following command on each node.

    ./xray stop all

  2. Extract the contents of the compressed archive and go to the extracted folder.

    tar -xvf jfrog-xray-<version>-compose.tar.gz
cd jfrog-xray-<version>-compose.tar.gz

    This .env file is used by docker-compose and is updated during installations and upgrades.

    Notice that some operating systems do not display dot files by default. If you make any changes to the file, remember to backup before an upgrade.

  3. Run the config.sh script to setup folders with required ownership. Note: the script will prompt you with a series of mandatory inputs, including if this is part of a cluster, and configure the needed system.yaml.

    ./config.sh

    Note: For the first node upgrade, make sure to select "N" when prompted if you are adding an additional node to an existing product cluster. For the following additional nodes, make sure to select "Y" and provide the Join Key and JFrog URL.

  4. Start the node. Note:Run this commandonlyfrom  the extracted folder.

    Manage Xray using docker-compose commands.

    cd jfrog-xray-<version>-compose

# Starting from Xray 3.8.x, PostgreSQL needs to be started before starting the other services.
if PostgreSQL 9.5.2 running use -   docker-compose -p xray-postgres -f docker-compose-postgres-9-5-2v.yaml up -d
if PostgreSQL 10.13  running use -   docker-compose -p xray-postgres -f docker-compose-postgres-10-13v.yaml up -d
if PostgreSQL 12.3   running use -   docker-compose -p xray-postgres -f docker-compose-postgres.yaml up -d

docker-compose -p xray up -d

docker-compose -p xray ps
docker-compose -p xray down



  5. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.

    docker-compose -p xray logs

  6. Check Xray Log.

RPM/Debian

Upgrading the First Node

  1. Stop all the cluster nodes that are setup using HA by running the following command on each node.

    service xray stop

    Make sure your MongoDB and PostgreSQL are running in the background.

  2. Extract the contents of the compressed archive and go to the extracted folder.

    tar -xvf jfrog-xray-<version>-rpm.tar.gz
    tar -xvf jfrog-xray-<version>deb.tar.gz

  3. Run the install.sh script to setup folders with required ownership.

    ./install.sh

  4. Add the following to the $<PostgreSQL home folder>/data/pg_hba.conf file.

    host    all             all             0.0.0.0/0               md5

  5. Add the following to the $<PostgreSQL home folder>/data/postgresql.conf file.

    listen_addresses='*'


  6. Restart PostgreSQL.

    service postgresql-<version> stop
service postgresql-<version> start

    From Xray version 3.x, RabbitMQ is packaged and managed as part of the Xray RPM. Any action (stop, start and status) on the main service of Xray will be performed on RabbitMQ as well.
    The existing RabbitMQ RPM which was installed as part of Xray version 2.x can be uninstalled after Xray 3.x is successfully installed and running.

  7. Start the Xray node.

    systemctl start xray.service
    systemctl start xray

    Manage Xray using the following commands.

    systemctl stop xray.service
    service xray stop|status|restart
  8. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.

  9. Check Xray Log.

    tail -f $JFROG_HOME/xray/var/log/console.log
Upgrading the additional Node

  1. Stop all the cluster nodes that are setup using HA by running the following command on each node.

    service xray stop


  2. Extract the contents of the compressed archive and go to the extracted folder.

    tar -xvf jfrog-xray-<version>-rpm.tar.gz
    tar -xvf jfrog-xray-<version>-deb.tar.gz

  3. Run the config.sh script to setup folders with required ownership.

    ./install.sh

  4. Modify the system.yaml file located in the $JFROG_HOME/xray/var/etc folder with the following configurations.

    shared:
   rabbitMq:
      active:
         node:
            name: <node-name> (use same name across all subsequent nodes)
            ip: <first-node-ip>

  5. Start the Xray node.

    systemctl start xray.service
    systemctl start xray

    Manage Xray using the following commands.

    systemctl stop xray.service
    service xray stop|status|restart
  6. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.

  7. Check Xray Log.

    tail -f $JFROG_HOME/xray/var/log/console.log

After the migration is successfully ended, it is recommended to complete the following steps:

  1. Validate that your Xray data has migrated successfully.
  2. Remove MongoDB configuration from the system.yaml.
  3. Uninstall the MongoDB database.


Upgrading from Version 3.x to 3.x

The following upgrade methods are supported:

Interactive Script Upgrade (Recommended)

The installer script works with all supported upgrade methods (RPM, Debian, and Docker Compose). It provides you an interactive way to upgrade Xray and its dependencies.

  1. Download Xray (RPM, Debian, or Docker Compose).

  2. Stop the service.

    systemctl stop xray.service
    service xray stop
    cd jfrog-xray-<version>-compose
docker-compose -p xray down

  3. Extract the contents of the compressed archive and go to the extracted folder. The installer script is located in the extracted folder.
    Note: For Docker Compose upgrades, make sure to merge any customizations in your current docker-compose.yaml file to the new extracted version of the     docker-compose.yaml file.

    tar -xvf jfrog-xray-<version>-<compose|rpm|deb>.tar.gz
cd jfrog-xray-<version>-<compose|rpm|deb>

    Copy the contents of the .env file in the previous installation to the newly created .env file in this archive without copying the versions, as this will affect the upgrade.

  4. Run the installer script.
    If needed, the script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.

    ./config.sh
    ./install.sh

  5. Start the Xray service.

    systemctl start xray.service
    systemctl start xray
    cd jfrog-xray-<version>-compose
docker-compose -p xray up -d
  6. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.

  7. Check Xray Log.

    tail -f $JFROG_HOME/xray/var/log/console.log

Manual RPM/Debian Upgrade

  1. Download Xray (RPM or Debian)

  2. Stop the current server.

    systemctl stop xray.service
    service xray stop

  3. Extract the contents of the compressed archive and go to the extracted folder.

    tar -xvf jfrog-xray-<version>-<rpm|deb>.tar.gz
cd jfrog-xray-<version>-<rpm|deb>

    Starting from Xray 3.8.x, RabbitMQ bundled with Xray has been upgraded, and it requires an upgrade of the Erlang library. This library can be found on $JFROG_HOME/xray/app/third-party. For more information, see Installing Erlang.

    To upgrade the dependencies for RabbitMQ, you will need to upgrade socat/erlang by using  "--replacefiles" to work around a file conflict error.

  4. Install Xray as a service on Red Hat compatible Linux distributions, as a root user.

    yum -y install ./xray/xray.rpm
    dpkg -i ./xray/xray.deb

  5. Start Xray.

    systemctl start xray.service
    systemctl start xray

  6. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.

  7. Check Xray Log.

    tail -f $JFROG_HOME/xray/var/log/console.log

Linux Archive Upgrade

Remember to back up the RabbitMQ password and to add it back to the rabbitmq.conf file.

  1. Stop the current server.

    cd $JFROG_HOME/xray/app/bin
./xray.sh stop

  2. Extract the contents of the compressed archive and go to the extracted folder.

    mv jfrog-xray-<version>-linux.tar.gz /opt/jfrog/
cd /opt/jfrog
tar -xf jfrog-xray-<version>-linux.tar.gz

    Starting from Xray 3.8.x, RabbitMQ bundled with Xray has been upgraded, and it requires an upgrade of the Erlang library. This library can be found on $JFROG_HOME/xray/app/third-party. For more information, see Installing Erlang.

  3. Replace the existing $JFROG_HOME/xray/app with the new app folder.

    # Export variables to simplify commands
export JFROG_HOME=/opt/jfrog
export JF_NEW_VERSION=/opt/jfrog/jfrog-xray-<version>-linux

# Remove app
rm -rf $JFROG_HOME/xray/app

# Copy new app
cp -fr $JF_NEW_VERSION/app $JFROG_HOME/xray/

# Remove extracted new version
rm -rf $JF_NEW_VERSION

  4. Manage Xray.

    $JFROG_HOME/xray/app/bin/xray.sh start|stop
  5. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Dashboard tab in the Application module in the UI.

  6. Check Xray Log.

    tail -f $JFROG_HOME/xray/var/log/console.log

Helm Upgrade

When upgrading from Xray 3.x to 3.x charts, due to breaking changes, use kubectl delete statefulsets <old_statefulset_xray_name> and run the helm upgrade.

Also, While upgrading from Xray 3.x to 4.x charts, due to breaking RabbitMQ (whenrabbitmq.enabled=true) subchart changes, run the following.

$ kubectl delete statefulsets <old_statefulset_xray_name>
$ kubectl delete statefulsets <old_statefulset_rabbitmq_name>
$ kubectl delete pvc <old_PVC_rabbitmq_name>
$ helm upgrade --install xray --namespace xray center/jfrog/xray

Downtime is required to perform an upgrade.

To upgrade Xray.

  1. Update the existing deployed version to the updated version.

    helm upgrade --set common.xrayVersion=[version number]/jfrog/xray

  2. If Xray was installed without providing a value to postgresql.postgresqlPassword (the password was autogenerated), follow these instructions.

    1. Get the current password by running the following.

      POSTGRES_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-postgresql -o jsonpath="{.data.postgresql-password}" | base64 --decode)

    2. Upgrade the release by passing the previously auto-generated secret.

      helm upgrade <myrelease> center/jfrog/xray --set postgresql.postgresqlPassword=${POSTGRES_PASSWORD}

  3. If Xray was installed without providing a value to rabbitmq.rabbitmqPassword/rabbitmq-ha.rabbitmqPassword (the password was autogenerated), follow these instructions.

    1. Get the current password by running the following.

      RABBITMQ_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-rabbitmq -o jsonpath="{.data.rabbitmq-password}" | base64 --decode)

    2. Upgrade the release by passing the previously auto-generated secret.

      helm upgrade <myrelease> center/jfrog/xray --set rabbitmq.rabbitmqPassword=${RABBITMQ_PASSWORD}/rabbitmq-ha.rabbitmqPassword=${RABBITMQ_PASSWORD}
  4. If Xray was installed with all of the default values (e.g., with no user-provided values for Rabbit/Postgres), follow these steps.
    1. Retrieve all current passwords (RabbitMQ/PostgreSQL) as explained in the above section.

    2. Upgrade the release by passing the previously auto-generated secrets.

      helm upgrade --install xray --namespace xray center/jfrog/xray --set rabbitmq-ha.rabbitmqPassword=<rabbit-password> --set postgresql.post
  5. Access Xray from your browser at: http://<jfrogUrl>/ui/, then go to the Security & Compliance tab in the Application module in the UI.

  6. Check the status of your deployed helm releases.

    helm status xray

Upgrading the Chart Versions from 1.x/2.x to 3.x and Above

  • JFrog Xray 3.x is only compatible with JFrog Artifactory 7.x; to upgrade, you must first install JFrog Artifactory 7.x.
  • To upgrade from a version prior to 1.x, you will first need to upgrade to the latest version of 1.x 
  • To upgrade from a version of 2.x, you first need to upgrade to the latest version of 2.x (for more information, see Upgrading Xray 2 documentation).
PostgreSQL Migration Process

The recommended migration process has two main steps:

  1. Migrate the existing MongoDB data to an existing PostgreSQL.
  2. Perform a full database export and import of PostgreSQL.
Prerequisite Step: Get the Details of the Existing Chart
  1. Block user access to Xray (but do not shut down).

  2. Get the service names OLD_PG_SERVICE_NAME, OLD_MONGO_SERVICE_NAME using the command below. For example: OLD_PG_SERVICE_NAME and OLD_MONGO_SERVICE_NAME values as <OLD_RELEASE_NAME>-postgresql and <OLD_RELEASE_NAME>-mongodb respectively.

    $ kubectl get svc
NAME                                       TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                       AGE
<OLD_RELEASE_NAME>-mongodb                 ClusterIP      10.101.56.69     <none>        27017/TCP                     114m
<OLD_RELEASE_NAME>-postgresql              ClusterIP      10.101.250.74    <none>        5432/TCP                      114m
<OLD_RELEASE_NAME>-rabbitmq-ha             ClusterIP      None             <none>        15672/TCP,5672/TCP,4369/TCP   114m
<OLD_RELEASE_NAME>-rabbitmq-ha-discovery   ClusterIP      None             <none>        15672/TCP,5672/TCP,4369/TCP   114m
<OLD_RELEASE_NAME>-xray-analysis           ClusterIP      10.104.138.63    <none>        7000/TCP                      114m
<OLD_RELEASE_NAME>-xray-indexer            ClusterIP      10.106.72.163    <none>        7002/TCP                      114m
<OLD_RELEASE_NAME>-xray-persist            ClusterIP      10.103.20.33     <none>        7003/TCP                      114m
<OLD_RELEASE_NAME>-xray-server             LoadBalancer   10.105.121.175   <pending>     80:32326/TCP                  114m

  3. Save the previous passwords OLD_PG_SERVICE_NAME, OLD_MONGO_SERVICE_NAME or extract them from the secret of the existing PostgreSQL and MongoDB pods.

    #Example:
OLD_PG_PASSWORD=$(kubectl get secret -n <namespace> <OLD_RELEASE_NAME>-postgresql -o jsonpath="{.data.postgres-password}" | base64 --decode)
OLD_MONGO_PASSWORD=$(kubectl get secret -n <namespace> <OLD_RELEASE_NAME>-mongodb -o jsonpath="{.data.mongodb-password}" | base64 --decode)

  4. Stop the old Xray pods (scale down replicas to 0). The PostgreSQL and MongoDB pods will still remain active.

    $ kubectl scale statefulsets <REPLACE_OLD_RELEASE_NAME>-rabbitmq-ha <REPLACE_OLD_RELEASE_NAME>-xray-analysis <REPLACE_OLD_RELEASE_NAME>-xray-indexer <REPLACE_OLD_RELEASE_NAME>-xray-persist <REPLACE_OLD_RELEASE_NAME>-xray-server --replicas=0
Migrate the Existing MongoDB Data to an Existing PostgreSQL

Run the helm install (not upgrade) with the new version say xray-new in the following way.

  1. Verify that all probes are disabled.

    --set router.livenessProbe.enabled=false --set router.readinessProbe.enabled=false --set indexer.livenessProbe.enabled=false --set analysis.livenessProbe.enabled=false --set server.livenessProbe.enabled=false --set persist.livenessProbe.enabled=false --set indexer.readinessProbe.enabled=false --set analysis.readinessProbe.enabled=false --set server.readinessProbe.enabled=false --set persist.readinessProbe.enabled=false

  2. Point to the previous PostgreSQL pod (user, password,DATABASE).

    --set postgresql.enabled=false --set database.user=<OLD_PG_USERNAME> --set database.password=<OLD_PG_PASSWORD> --set database.url="postgres://<SERVICE_NAME_POSTGRES>:5432/xraydb?sslmode=disable"

  3. Point to the previous MongoDB (user, password,DATABASE) pod.

    --set xray.mongoUsername=<OLD_MONGO_USERNAME> --set xray.mongoPassword=<OLD_MONGO_PASSWORD> --set xray.mongoUrl="mongodb://<SERVICE_NAME_MONGODB>:27017/?authSource=xray&authMechanism=SCRAM-SHA-1"

    This will trigger the migration process as per the example below.

    # Create a customvalues.yaml file

router: 
  livenessProbe:
    enabled: false
  readinessProbe: 
    enabled: false
indexer: 
  livenessProbe:
    enabled: false
  readinessProbe: 
    enabled: false
analysis: 
  livenessProbe:
    enabled: false
  readinessProbe: 
    enabled: false
server: 
  livenessProbe:
    enabled: false
  readinessProbe: 
    enabled: false  
persist: 
  livenessProbe:
    enabled: false
  readinessProbe: 
    enabled: false
postgresql:
  enabled: false
database: 
  user: <OLD_PG_USERNAME>
  password: <OLD_PG_PASSWORD>
  url: "postgres://<SERVICE_NAME_POSTGRES>:5432/xraydb?sslmode=disable"
xray: 
  mongoUsername: <OLD_MONGO_USERNAME>
  mongoPassword: <OLD_MONGO_PASSWORD>
  mongoUrl: "mongodb://<SERVICE_NAME_MONGODB>:27017/?authSource=xray&authMechanism=SCRAM-SHA-1"
  masterKey: <PREVIOUS_MASTER_KEY>
  jfrogUrl: <NEW_ARTIFACTORY_URL>
  joinKey: <JOIN_KEY>
rabbitmq:
  enabled: true
  auth: 
    password: <PASSWORD>
rabbitmq-ha:
  enabled: false

  4. Apply the values.yaml file during installation.

    helm upgrade --install xray-new center/jfrog/xray -f customvalues.yaml
  5. Stop the new Xray pods (scale down replicas to 0). Both PostgreSQL pods still remain active.

  6. Create a customvalues.yaml file.

    replicaCount: 0
postgresql:
  postgresqlPassword: <NEW_PG_PASSWORD>
rabbitmq:
  enabled: true
  auth:
    password: <PASSWORD>
rabbitmq-ha:
  enabled: false
xray: 
  masterKey: <PREVIOUS_MASTER_KEY>
  jfrogUrl: <NEW_ARTIFACTORY_URL>
  joinKey: <JOIN_KEY>
unifiedUpgradeAllowed: true
databaseUpgradeReady: true

  7. Apply the values.yaml file during installation.

    helm upgrade --install xray-new center/jfrog/xray -f customvalues.yaml

Perform a Full Database Export and Import of PostgreSQL

To migrate PostgreSQL data between old and new pods.

  1. Connect to the new PostgreSQL pod (you can obtain the name by running kubectl get pods).

    $ kubectl exec -it <NAME> bash

  2. Once logged in, create a dump file from the previous database using pg_dump, and connect to the previous PostgreSQL chart.

    $ pg_dump -h <OLD_PG_SERVICE_NAME> -U xray DATABASE_NAME > /tmp/backup.sql

    After running this command, you will be prompted for a password; this password is the previous chart password OLD_PG_PASSWORD. This operation could take some time depending on the database size.

  3. Once you have the backup file, you can restore it with this command.

  4. $ psql -U xray DATABASE_NAME < /tmp/backup.sql

    After running the command above, you will be prompted for a password; this is the current chart password. This operation could take some time depending on the database size.

  5. Next, run the upgrade command one final time to start Xray. 

    # Create a customvalues.yaml file
xray: 
  masterKey: <PREVIOUS_MASTER_KEY>
  jfrogUrl: <NEW_ARTIFACTORY_URL>
  joinKey: <JOIN_KEY>
rabbitmq:
  enabled: true
  auth: 
    password: <PASSWORD>
rabbitmq-ha:
  enabled: false
postgresql:
  postgresqlPassword: <NEW_PG_PASSWORD>
unifiedUpgradeAllowed: true
databaseUpgradeReady: true

  6. Apply the values file during the installation.

    helm upgrade --install xray-new center/jfrog/xray -f customvalues.yaml

  7. Restore access to the new Xray by running the command below to remove the old Xray deployment and Helm release.

    run helm delete <OLD_RELEASE_NAME>

Xray should now be ready for use.

RabbitMQ Migration Process

The RabbitMQ-HA chart has been removed from the 7.x chart versions; therefore, before upgrading to the 7.x chart versions, you will need to perform the RabbitMQ migration (assuming you are not using the Bitnami RabbitMQ). This section describes the steps for migrating from the RabbitMQ-HA chart to the Bitnami RabbitMQ chart before upgrading to chart version 7.x and above.

For this procedure, you will need to choose whether to migrate without existing queues (assuming that all queues are empty) or to migrate while Xray is down.

Migrating without Existing Queues

This procedure assumes that all queues are empty.

While running the helm upgrade, make sure that there are no indexing or Watches running.

Upgrade Xray with Bitnami RabbitMQ (disabling RabbitMQ-HA).

yaml
     rabbitmq-ha:
       enabled: false
     rabbitmq:
       enabled: true
       auth:
         username: guest
         password: password


Migrating with Existing Queues

This migration option, which requires downtime, is intended for situations where there are unfinished tasks running in Xray, but the migration to Bitnami RabbitMQ is necessary.

  1. Detach (disable) Xray in Artifactory.

  2. Upgrade Xray with both RabbitMQs (RabbitMQ-HA and Bitnami RabbitMQ) and scale down the Xray services to 0 (replicaCount: 0).

    Both RabbitMQs should be scaled down to one replica. Both RabbitMQs should have the ha-mode: all set (by default they should already be set).

    yaml
     xray:
     replicaCount: 0
     rabbitmq-ha:
       enabled: true
       replicaCount: 1
     rabbitmq:
       enabled: true
       replicaCount: 1
       auth:
         username: guest
         password: guest

  3. Go into the Bitnami RabbitMQ pod and run the following.

    bash
    export OLD_RMQ=rabbit@`<RELEASE_NAME>`-rabbitmq-ha-0.`<RELEASE_NAME>`-rabbitmq-ha-discovery.`<NAMESPACE_NAME>`.svc.cluster.local && \
    rabbitmqctl stop_app && \
    rabbitmqctl join_cluster $OLD_RMQ && \
    rabbitmqctl start_app


    The process of data synchronization between     RabbitMQ -HA and the new Bitnami RabbitMQ node begins.

  4. Verify the synchronization with the queue size and count using the command rabbitmqctl list_queues. The synchronization status can also be viewed from the RabbitMQ dashboard of the old RabbitMQ (RabbitMQ-HA).

  5. When all the data has been synchronized between the cluster nodes, run a helm upgrade to disable the RabbitMQ-HA. This removes the old RabbitMQ-HA and brings up the Xray services.

    yaml
     xray:
     replicaCount: 1
     rabbitmq-ha:
       enabled: false
     rabbitmq:
       enabled: true
       replicaCount: 1
       auth:
         username: guest
         password: guest

  6. Finally, remove the old node from the Bitnami RabbitMQ.

    bash
     rabbitmqctl forget_cluster_node rabbit@`<RELEASE_NAME>`-rabbitmq-ha-0.`<RELEASE_NAME>`-rabbitmq-ha-discovery.`<NAMESPACE_NAME>`.svc.cluster.local

  7. Enable Xray in Artifactory.

HA Upgrade

This section describes the process of upgrading your Xray High Availability cluster using the interactive script. The upgrade supports the following installation types:

  • Linux Archive
  • Docker Compose
  • RPM/Debian

Follow these steps to upgrade Xray using the interactive script.

Before running the upgrade on Linux and Native installers, you will need to stop RabbitMQ. Because shared.rabbitMq.autoStop is set to false by default. to be able to run RabbitMQ with systemctl/xray.sh, you will need to set shared.rabbitMq.autoStop to true.in the system.yaml . 

For Docker Compose, you will need to run the

docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml down

  1. Stop the Xray services on all secondary nodes.

    You must stop the services on the secondary nodes before stopping the services on the master node.

    $JFROG_HOME/xray/app/bin/xray.sh stop
    docker-compose -p xray down
    systemctl stop xray

  2. Next, stop the Xray services on the master node.

    $JFROG_HOME/xray/app/bin/xray.sh stop
    docker-compose -p xray down
    systemctl stop xray
  3. For Linux Archive only: Delete the app folder on all nodes (master and secondary). 

  4. Upgrade Xray on the master node by running the installer script.
    If needed, the script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.

    ./config.sh
  5. ./install.sh

  6. Start the Xray services on the master node.

    $JFROG_HOME/xray/app/bin/xray.sh start
    docker-compose -p xray up -d
    systemctl start xray

  7. Upgrade Xray on the secondary nodes.

    ./config.sh
    config.sh/install.sh

  8. Start the Xray services on the secondary nodes.

    $JFROG_HOME/xray/app/bin/xray.sh start
    docker-compose -p xray up -d
    systemctl start xray