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 (RPM, Debian and Docker Compose)
• Manual RPM
• Manual Debian

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

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, Xray will not use MongoDB except during the migration phase. Make sure both the databases are up and running before Xray services are started. During the migration, Xray will not be accessible. You can uninstall MongoDB 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

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 works.

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, Xray will not use MongoDB except during migration. 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. You can uninstall MongoDB 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

HA Upgrade

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

The following installation methods are supported:

• Docker Compose
• RPM / Debian

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.

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.
   

   Run this command only from  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

Upgrading from Version 3.x to 3.x

The following upgrade methods are supported:

• Interactive Script (Recommended)
• Manual RPM / Debian
• Linux Archive
• Helm

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. Store the RabbitMQ password securely before you proceed with the upgrade.
   You can find the password inside the file, $JFROG_HOME/app/bin/rabbitmq/rabbitmq.conf.



4. 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.

5. 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

6. Update the RabbitMQ password inside the file, $JFROG_HOME/app/bin/rabbitmq/rabbitmq.conf, with the password that you previously stored.
   
   

7. Start Xray.
   

   systemctl start xray.service

   systemctl start xray

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

Linux Archive Upgrade

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

$ 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 jfrog/xray

kubectl cp ./comp_-6795364578871.zip <namespace>/xray-0:/opt/jfrog/xray/var/work/server/updates/component/comp_-6795364578871.zip -c xray-server
kubectl cp ./vuln_-6795364578871.zip <namespace>/xray-0:/opt/jfrog/xray/var/work/server/updates/vulnerability/vuln_-6795364578871.zip -c xray-server

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> jfrog/xray --set postgresql.postgresqlPassword=${POSTGRES_PASSWORD}

3. If Xray was installed without providing a value to rabbitmq.auth.password (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> jfrog/xray --set rabbitmq.auth.password=${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 jfrog/xray --set rabbitmq.auth.password=<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 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 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 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

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

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

Starting from version 3.31.0 and later, Xray supports hot upgrade for HA installations. Unlike regular upgrades, you need not turn off the secondary nodes while upgrading a node.

To perform a hot upgrade, ensure that all the nodes in the HA cluster run on the same version. For example, you cannot perform hot upgrade if one node is in version 3.31.0 and the two other nodes are in 3.31.1. While the upgrade is in process, you cannot do a DB sync. You must not restart any node while hot upgrade is in process. If you restart a node in the middle of the process, the node will not be able to rejoin the cluster. The JFrog Platform UI displays a warning message while the upgrade is in process. You cannot downgrade to a previous version using the hot upgrade process

Upgrade from Versions Higher than 3.31.0

Follow these steps to upgrade Xray using the interactive script on each node in the cluster.

1. Stop the Xray service on the node that you want to upgrade.
   

   
   

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

   docker-compose -p xray down

   systemctl stop xray

2. For Linux Archive only: Delete the app folder. 
   

3. Upgrade Xray by running the installer script.
   If needed, the script prompts you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.

   ./config.sh

4. ./install.sh

5. Start the Xray services.
   

   $JFROG_HOME/xray/app/bin/xray.sh start

   docker-compose -p xray up -d

   systemctl start xray

Upgrade from Versions Prior to 3.31.0

Follow these steps to upgrade Xray using the interactive script.

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