Upgrading from Xray Version 3.x to 3.x

The following upgrade methods are supported: The installer script works with all supported upgrade methods (RPM, Debian, and Docker Compose).

The following upgrade methods are supported:

Interactive Script Upgrade (Recommended)
Manual RPM / Debian
Linux Archive
Helm
High Availability Upgrade

⚠️
Upgrading to Xray 3.70.x - 3.84.x
Starting from Xray 3.70.x versions, Xray utilizes the pg_trgm PostgreSQL extension, which enhances Xray performance. This extension is not packaged until Xray version 3.84.x. If you are using an external PostgreSQL and this extension is not already installed, install the extension manually. For more information, see Support for pg_trgm Module

⚠️
Upgrading from Xray 3.71 to Higher Versions in Debian and Red Hat Installations
When you upgrade from Xray 3.71 to higher versions, Xray service might not come up after installation. This is because of an incompatible Erlang package in RabbitMQ. You must remove the Erlang package from your installation before you proceed with the upgrade.
If you upgraded to a higher version, run the following commands:
dpkg --purge --force-all esl-erlang
cd jfrog-xray-<version>-deb/third-party/rabbitmq
dpkg -i esl-erlang_23.2.3-1_ubuntu_bionic_amd64.deb
systemctl start xray.service

⚠️
Upgrading from Xray 3.16.2 to 3.69.3 in Debian Installations
When you upgrade from Xray 3.16.2 to higher versions, Xray service might not come up after installation. This is because of an incompatible Erlang package in RabbitMQ. You must remove the Erlang package from your installation before you proceed with the upgrade.
If you upgraded to a higher version, run the following commands.
dpkg --purge --force-all esl-erlang
cd jfrog-xray-<version>-deb/third-party/rabbitmq
dpkg -i esl-erlang_23.2.3-1_ubuntu_bionic_amd64.deb
systemctl start xray.service

⚠️
RabbitMQ Upgrade to version 3.11.x and later
Xray version 3.70.0 and later includes RabbitMQ version 3.11.x later. An upgrade to Rabbit MQ 3.11.x requires feature flags to be enabled. For more information, refer to Required Feature Flags in RabbitMQ 3.11.0.

Xray Single Node Interactive Script Upgrade (Recommended)

⚠️
Upgrading to Xray 3.70.0 or later from an Xray version prior to 3.70.0
If you are upgrading to Xray 3.70.0 or later from an Xray version prior to 3.70.0, your installation contains RabbitMQ 3.8.x. Feature flags in RabbitMQ have to be enabled before you can upgrade, since Xray 3.70.0 and later contains RabbitMQ 3.11.x and later.
Before you proceed with the upgrade, go to RabbitMQ Upgrade to version 3.11.x and set feature flags in RabbitMQ.

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.

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

Stop the service.

systemd OS

systemctl stop xray.service

systemv OS

service xray stop

Docker Compose

cd jfrog-xray-<version>-compose
docker-compose -p xray down

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>
```
Note: For Docker Compose upgrades, make sure to merge any customizations in your current docker-compose.yaml file to the new extracted version of thedocker-compose.yamlfile.

📘
Note
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.

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.

Compose
```
./config.sh
```
RPM/DEB
```
./install.sh
```

Start the Xray service.

systemd OS

systemctl start xray.service

systemv OS

systemctl start xray

Docker Compose

cd jfrog-xray-<version>-compose
docker-compose -p xray up -d

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

Check Xray Log.

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

Xray version 3.70.0 and later includes RabbitMQ version 3.11.x later. An upgrade to Rabbit MQ 3.11.x requires feature flags to be enabled. For more information, refer to Required Feature Flags in RabbitMQ 3.11.0.

You need to manually run the migration operation for RabbitMQ before you start Xray upgrade for your Linux installation (RPM, Debian, and Linux Archive).

Run the following command in the nodes that run RabbitMQ.

sudo -H -u xray bash -c 'export RABBITMQ_FEATURE_FLAGS="drop_unroutable_metric,empty_basic_get_metric,implicit_default_bindings,maintenance_mode_status,quorum_queue,stream_queue,user_limits,virtual_host_metadata"'
sudo -H -u xray bash -c '/opt/jfrog/xray/app/third-party/rabbitmq/sbin/rabbitmqctl enable_feature_flag all'

Run the following command inside the RabbitMQ container.

rabbitmqctl enable_feature_flag all

Xray Single Node Linux Archive Upgrade

⚠️
Upgrading to Xray 3.70.0 or later from an Xray version prior to 3.70.0
If you are upgrading to Xray 3.70.0 or later from an Xray version prior to 3.70.0, your installation contains RabbitMQ 3.8.x. Feature flags in RabbitMQ have to be enabled before you can upgrade, since Xray 3.70.0 and later contains RabbitMQ 3.11.x and later.
Before you proceed with the upgrade, go to RabbitMQ Upgrade to version 3.11.x and set feature flags in RabbitMQ.

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

Stop the current server.

Stop Xray

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

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

Untar

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

📘
Note
Starting from Xray 3.8.x, RabbitMQ bundled with Xray has been upgraded, and the Erlang library requires an upgrade (You might need to remove the Erlang package from your installation and install the latest version). This library can be found on $JFROG_HOME/xray/app/third-party.
Example for Deb:
dpkg --purge --force-all esl-erlangcd jfrog-xray-<version>-linux/app/third-party/rabbitmqdpkg -i esl-erlang_26.1.2-1~debian~bullseye_amd64.debsystemctl start xray.service
Example for RPM:
rpm -e --nodeps erlangcd jfrog-xray-<version>-linux/app/third-party/rabbitmqrpm -ivh erlang-26.1.2-1.el8.x86_64.rpmsystemctl start xray.service

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

Upgrade

# 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

Manage Xray.

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

Access Xray from your browser at:http://<jfrogUrl>/ui/, go theDashboard tab in theApplicationmodule in the UI.

Check Xray Log.

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

You need to manually run the migration operation for RabbitMQ before you start Xray upgrade for your Linux installation (RPM, Debian, and Linux Archive).

Run the following command in the nodes that run RabbitMQ.

sudo -H -u xray bash -c 'export RABBITMQ_FEATURE_FLAGS="drop_unroutable_metric,empty_basic_get_metric,implicit_default_bindings,maintenance_mode_status,quorum_queue,stream_queue,user_limits,virtual_host_metadata"'
sudo -H -u xray bash -c '/opt/jfrog/xray/app/third-party/rabbitmq/sbin/rabbitmqctl enable_feature_flag all'

Xray Single Node Manual RPM/Debian Upgrade

⚠️
Upgrading from Xray 3.16.2 to 3.69.3 in Debian Installations
When you upgrade from Xray 3.16.2 to higher versions, Xray service might not come up after installation. This is because of an incompatible Erlang package in RabbitMQ. You must remove the Erlang package from your installation before you proceed with the upgrade.
If you upgraded to a higher version, run the following commands.
dpkg --purge --force-all esl-erlang
cd jfrog-xray-<version>-deb/third-party/rabbitmq
dpkg -i esl-erlang_23.2.3-1_ubuntu_bionic_amd64.deb
systemctl start xray.service

⚠️
Upgrading to Xray 3.70.0 or later from an Xray version prior to 3.70.0
If you are upgrading to Xray 3.70.0 or later from an Xray version prior to 3.70.0, your installation contains RabbitMQ 3.8.x. Feature flags in RabbitMQ have to be enabled before you can upgrade, since Xray 3.70.0 and later contains RabbitMQ 3.11.x and later.
Before you proceed with the upgrade, go to RabbitMQ Upgrade to version 3.11.x and set feature flags in RabbitMQ.

⚠️
Install/Upgrade Xray 3.70.0 to 3.74.0 with RPM
Xray installation/upgrade might fail because of the missing libltdl RPM package. Download and install the package, and proceed with the installation/upgrade of Xray.

Download Xray (RPM or Debian).
Stop the current server.

systemd OS
```
systemctl stop xray.service
```
systemv OS
```
service xray stop
```
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.
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>
```

📘
Note
Starting from Xray 3.8.x, RabbitMQ bundled with Xray has been upgraded, and the Erlang library requires an upgrade (You might need to remove the Erlang package from your installation and install the latest version). This library can be found on $JFROG_HOME/xray/app/third-party.
Example for Deb:
dpkg --purge --force-all esl-erlangcd jfrog-xray-<version>-deb/third-party/rabbitmqdpkg -i esl-erlang_26.1.2-1~debian~bullseye_amd64.debsystemctl start xray.service
Example for RPM:
rpm -e --nodeps erlangcd jfrog-xray-<version>-rpm/third-party/rabbitmqrpm -ivh erlang-26.1.2-1.el8.x86_64.rpmsystemctl start xray.service

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

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

RPM
```
yum -y install ./xray/xray.rpm
```
Debian
```
dpkg -i ./xray/xray.deb
```bash
```
Update the RabbitMQ password inside the file, $JFROG_HOME/app/bin/rabbitmq/rabbitmq.conf, with the password that you previously stored.

Start Xray.

systemd OS

systemctl start xray.service

systemv OS

systemctl start xray

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

Check Xray Log.

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

You need to manually run the migration operation for RabbitMQ before you start Xray upgrade for your Linux installation (RPM, Debian, and Linux Archive).

Run the following command in the nodes that run RabbitMQ.

sudo -H -u xray bash -c 'export RABBITMQ_FEATURE_FLAGS="drop_unroutable_metric,empty_basic_get_metric,implicit_default_bindings,maintenance_mode_status,quorum_queue,stream_queue,user_limits,virtual_host_metadata"'
sudo -H -u xray bash -c '/opt/jfrog/xray/app/third-party/rabbitmq/sbin/rabbitmqctl enable_feature_flag all'

Xray Single Node Manual Docker Compose Upgrade

⚠️
Upgrading to Xray 3.70.0 or later from an Xray version prior to 3.70.0
If you are upgrading to Xray 3.70.0 or later from an Xray version prior to 3.70.0, your installation contains RabbitMQ 3.8.x. Feature flags in RabbitMQ have to be enabled before you can upgrade, since Xray 3.70.0 and later contains RabbitMQ 3.11.x and later.
Before you proceed with the upgrade, go to RabbitMQ Upgrade to version 3.11.x and set feature flags in RabbitMQ.

Download Xray (Docker Compose).
Stop the current server.

Stop Xray
```
docker-compose -p xray down
```
Extract the contents of the compressed archive and go to the extracted folder.

Untar
```
tar -xvf jfrog-xray-<version>-compose.tar.gz
```

📘
.env file included within the Docker-Compose archive
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've made any changes to the file, remember to backup before an upgrade.

Copy the docker-compose template from the templates folder to the extracted folder. Rename it as docker-compose.yaml. Ensure that you use the same template as you did during the installation.

📘
Docker for Mac
When you use Docker Compose in Mac, /etc/localtime might not work as expected since it might not be a shared location in the docker-for-mac settings.
You can remove the following line from the selected template file to avoid installation issues.
- /etc/localtime:/etc/localtime:ro

Requirement	Template
Xray	docker-compose.yaml
RabbitMQ	docker-compose-rabbitmq.yaml
PostgreSQL	docker-compose-postgres.yaml

Update the .env file and ensure that you use the same values when you did the installation.

## The Installation directory for Xray. If not entered, the script will prompt you for this input. Default [$HOME/.jfrog/xray]
ROOT_DATA_DIR=

# Host ID. Other nodes in the cluster will use this ID to identify this node
HOST_ID=

# ID of the active node. Please leave the value as "None" for active nodes. (shared.rabbitMq.active.node.name).  
JF_SHARED_RABBITMQ_ACTIVE_NODE_NAME=None 

# IP of the active node. (shared.rabbitMq.active.node.ip)
JF_SHARED_RABBITMQ_ACTIVE_NODE_IP=127.0.0.1

# Bind IP for Internal ports of Third party applications
JF_THIRD_PARTY_BIND_IP=127.0.0.1
```bash

Start Xray and PostgreSQL using docker-compose commands.

## RabbitMQ needs to be started before starting other services
docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml up -d
  
## From Xray 3.8.x, PostgreSQL needs to be started before starting the other services.
docker-compose -p xray-postgres -f docker-compose-postgres.yaml up -d
 
docker-compose -p xray up -d
 
## Check whether service is up
docker-compose -p xray ps

Access Xray from your browser at:http://<jfrogUrl>/ui/, go theDashboard tab in theApplicationmodule in the UI.
Check Xray Log.
```
docker ps
docker-compose -p xray logs
```

⚠️
Configure log rotation of the console log
The console.log file can grow quickly since all services write to it. For more information, see configure the log rotation.

Run the following command inside the RabbitMQ container.

rabbitmqctl enable_feature_flag all

Xray Helm Upgrade

📘
Note
When upgrading from Xray chart version 3.x to 3.x, due to breaking changes, use kubectl delete statefulsets <old_statefulset_xray_name> and run the helm upgrade.
Also, While upgrading from Xray chart version 3.x to 4.x, due to breaking RabbitMQ (whenrabbitmq.enabled=true) subchart changes, run the following commands.
$ 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

📘
Note
Downtime is required to perform an upgrade.

📘
Offline Update
If you wish to do an offline update of the Xray database while running in pods, copy the downloaded data into the correct Xray container (scale down to 1 replica if needed before) and then using kubectl commands copy the file to the specific location.
For example:
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

⚠️
Upgrading to Xray 3.70.0 or later from an Xray version prior to 3.70.0
If you are upgrading to Xray 3.70.0 or later from an Xray version prior to 3.70.0, your installation contains RabbitMQ 3.8.x. Feature flags in RabbitMQ have to be enabled before you can upgrade, since Xray 3.70.0 and later contains RabbitMQ 3.11.x and later.
Before you proceed with the upgrade, go to RabbitMQ Upgrade to version 3.11.x and set feature flags in RabbitMQ.

To upgrade Xray.

Update the existing deployed version to the updated version.

helm repo update

helm upgrade --install <myrelease> namespace xray jfrog/xray

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}
```bash
```
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}
```
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 previous 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
```
Access Xray from your browser at: http://<jfrogUrl>/ui/, then go to the Xray tab in the Application module in the UI.
Check the status of your deployed helm releases.
```
helm status xray
```

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.

The recommended migration process has two main steps:

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

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

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)

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.

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

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"

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 like in the following example.

# 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

Apply the values.yaml file during installation.

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

Stop the new Xray pods (scale down replicas to 0). Both PostgreSQL pods still remain active.

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

Apply the values.yaml file during installation.

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

To migrate PostgreSQL data between old and new pods.

Connect to the new PostgreSQL pod (you can obtain the name by running kubectl get pods).
```
$ kubectl exec -it <NAME> bash
```sql
```
Once logged in, create a dump file from the previous database usingpg_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 passwordOLD_PG_PASSWORD. This operation could take some time depending on the database size.
Once you have the backup file, you can restore it with this command.
```
$ 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.

Create a customvalues.yaml file.

# 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

Apply the values file during the installation.

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

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.

📘
Note
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 beforeupgrading 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.

📘
Important
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

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.

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

📘
Note
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

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

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 betweenRabbitMQ-HA and the new BitnamiRabbitMQnode begins.

Verify the synchronization with the queue size and count using the command rabbitmqctl list_queues.

You can also view the synchronization status from the RabbitMQ dashboard of the old RabbitMQ (RabbitMQ-HA).

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

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

Enable Xray in Artifactory.

For Helm, we have added a pre-upgrade hook that enables feature flags in RabbitMQ before the upgrade to version 3.11.x and later. The hook runs automatically when you run the upgrade command. You can disable the hook for the subsequent upgrades.

Manual Migration Operation

You can also do the migration operation manually before you start the upgrade.

Run the following command inside the RabbitMQ container.

rabbitmqctl enable_feature_flag all

Ensure that you disable the pre-upgrade hook after you perform manual migration.

Disable Pre-upgrade Hook

Update the following values in the values.yaml file to disable the pre-upgrade hook.

rabbitmq.migration.enabled=false
rabbitmq.rabbitmqUpgradeReady=true

You can also pass these values along with the Helm upgrade command.

For example:

$ helm upgrade --install xray --namespace xray jfrog/xray --set rabbitmq.migration.enabled=false --set rabbitmq.rabbitmqUpgradeReady=true

Xray 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

For more information on HA upgrade in Helm, see Xray Helm Upgrade.

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

📘
Note
Since Xray supports hot upgrade from version 3.31.0, you can perform hot upgrade to upgrade the HA installation in 3.31.0 to a version higher than 3.31.0.

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

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

Linux Archive
```
$JFROG_HOME/xray/app/bin/xray.sh stop
```
Docker Compose
```
docker-compose -p xray down
```
RPM/Debian
```
systemctl stop xray
```
ForLinux Archive only: Delete theappfolder.
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.

Linux Archive/Docker Compose
```
./config.sh
```
RPM/Debian
```
./install.sh
```

Start the Xray services.

Linux Archive

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

Docker Compose

docker-compose -p xray up -d

RPM/Debian

systemctl start xray

Follow these steps to upgrade Xray using the interactive script.

📘
Linux and Native Installers
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 .

📘
Docker Compose
For Docker Compose, you will need to run the
docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml down

Stop the Xray services on all secondary nodes.

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

Linux Archive

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

Docker Compose

docker-compose -p xray down

RPM/Debian

systemctl stop xray

Next, stop the Xray services on the master node.

Linux Archive
```
$JFROG_HOME/xray/app/bin/xray.sh stop
```
Docker Compose
```
docker-compose -p xray down
```
RPM/Debian
```
systemctl stop xray
```
For Linux Archive only: Delete the app folder on all nodes (master and secondary).
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.

Linux Archive/Docker Compose
```
./config.sh
```
RPM/Debian
```
./install.sh
```
Start the Xray services on the master node.

Linux Archive
```
$JFROG_HOME/xray/app/bin/xray.sh start
```
Docker Compose
```
docker-compose -p xray up -d
```
RPM/Debian
```
systemctl start xray
```
Upgrade Xray on the secondary nodes.

Linux Archive/Docker Compose
```
./config.sh
```
RPM/Debian
```
config.sh/install.sh
```
Start the Xray services on the secondary nodes.

Linux Archive
```
$JFROG_HOME/xray/app/bin/xray.sh start
```
Docker Compose
```
docker-compose -p xray up -d
```
RPM/Debian
```
systemctl start xray
```

Updated 2 days ago