Cloud customer?
 Upgrade in MyJFrog >

Search





Overview

The new JFrog Platform requires Xray to be connected to a single Artifactory instance.

If you have one Xray instance connected to more than one Artifactory instances, before upgrading use the below procedure to move to this new requirement.

Upgrading Aritfactory or Xray without changing this requirement will cause data loss which cannot be restored.

Prerequisite

Your Xray instance must be upgraded to a version between 2.7 and 2.11.x.


Page Contents


Option 1: Pairing without configuration data (recommended)

This option will take you through disconnecting all Artifactory instances from your single Xray instance, except for one. Then, continuing to upgrade the disconnected Artifactory instances to version 7.x with newly installed Xray version 3.x instances.

This procedure will require re-indexing the additional Artifactory instances, and will cause some loss of Xray configuration data. You will need to: 

Many to One PairingOne to One Pairing


Procedure Steps

  1. Export user-defined configurations (Optional for Xray v 2.11 and up)
    You can export Xray user-defined configurations to be imported to other Xray instances using a set of dedicated REST APIs. The following settings include policies, watches, Ignore Rules, custom licenses, custom issues, webhooks, mail server, proxy configurations, and indexed resource settings.
  2. Disconnect Artifactory Xray pairings, except one
    Remove all Artifactory instances connected to Xray, except the one you would like to keep connected to this Xray instance. If you have an Artifactory instance that is configured as your authentication provider, keep this instance enabled with Xray.
    In the Xray UI, go to Admin | Artifactory, and delete the Artifactory instance(s) to remove. 
    Note: This operation will remove all data for the removed Artifactory instances.
  3. Upgrade the remaining connected Xray Artifactory pairing
    1. Upgrade the connected Artifactory instance to version 7.x, using this guide.
    2. Upgrade the connected Xray instance to version 3.x, using this guide.
      Note: Make sure to upgrade Artifactory before Xray.
  4. Upgrade disconnected Artifactory instances to 7.x, using this guide.
  5. Install new Xray 3.x instances for each Artifactory instance, using this guide.
    When installing the new Xray instances, make sure to provide the base URL and join key of the Artifactory instance you want to pair your Xray with.
  6. Import user-defined configurations (Optional for Xray v 2.11 and up)
    You can import Xray user-defined configurations, if you chose to export them in the first step. 
  7. Index all required resources for each one of the new Artifactory Xray pairs
    From the UI, in the Administration module, go to Xray Security and Compliance | General and click Indexed Resources



Option 2: Pairing with configuration data

This option will take you through installing additional Xray version 2.x instances for each Artifactory instance that you have, and restore all MongoDB and PostgreSQL data. Then, you can continue to upgrade each Artifactory and Xray pairs to version 7.x and version 3.x.

This procedure is more complex and is only suggested if you must keep all your Xray configurations and easily reconfigure them in the new instances.

Many to One PairingOne to One Pairing


Procedure Steps

The following main steps are included:

  1. Stop Xray services
  2. Backup Xray data folder
  3. Install new Xray and update configuration files
  4. Restore MongoDB and PostgreSQL
  5. Start the New Xray instance
  6. Additional Xray instances
  7. Remove unnecessary Artifactory Xray Pairing

Step 1: Stop Xray services

The following set of steps will disable your Xray instance from all except one Artifactory instance, handle pending tasks in Xray's queues, and stop the Xray service. 

  1. Configure one of your Artifactory instances as your authentication provider, if you do not have one already configured.
    In the Xray UI, go to Admin | Authentication, and select your Artifactory instance.
  2. Disable Xray integration from your Artifactory instances. If you have an Artifactory instance that is configured as your authentication provider, keep this instance enabled with Xray.
    In the Artifactory UI, go to Admin | JFrog Xray, and disable the Xray integration.

  3. Stop Xray.
    Note: Do not stop the PostgreSQL and MongoDB.

Step 2: Backup Xray data folder

  1. Compress and copy a backup file of your Xray data.

    cd <XRAY_HOME>
    tar -zcvf xray.backup.tar.gz xray


  2. Create MongoDB dumps.

    Create a dump file
    mongodump -d xray -u xray -p password -o mongodump
    
    Compress the dump file
    tar -czvf mongodump.tar.gz mongodump
  3. Create PostgreSQL dumps.

    Create a dump file
    pg_dump -U xray xraydb > /postgresdump
    Compress the dump file
    tar -czvf postgresdump.tar.gz postgresdump

Step 3: Install new Xray and update configuration files

  1. Install a new instance of Xray on a separate machine.
  2. Unzip and Restore Xray backup data.
    1. Change the new $XRAY_HOME folder name to xray_tmp (this will be deleted once the configuration update is complete).
      Note: This folder includes the following folders: backup, config, data, db_migraitons

      mv xray xray_tmp
    2. Copy the Xray data backup file, from the previous installation, xray.backup.tar.gz into the new $XRAY_HOME folder.
    3. Extract the Xray data backup file.

      tar -xvf xray.backup.tar.gz
    4. Verify that a new Xray folder is created, and its structure is the same as the xray_tmp structure.
    5. Remove the xray_tmp folder.

      rm xray_tmp


  3. Modify the Xray configuration file /var/opt/jfrog/xray/config/xray_config.yaml with the postgres, mongodb, rabbitmq parameters.

    ---
        ver:                   1.0
        XrayServerPort:       8000
        mqBaseUrl:            amqp://guest:guest@rabbitmq:5672
        mongoUrl:             mongodb://xray:password@mongodb:27017/?authSource=xray&authMechanism=SCRAM-SHA-1
        postgresqlUrl:        postgres://xray:xray@postgres:5432/xraydb?sslmode=disable
    
    

Step 4: Restore MongoDB and PostgreSQL

MongoDB

  1. Copy the MongoDB backup zip file mongodump.tar.gz to the new machine.
  2. Extract the MongoDB backup file.

    tar -xvf mongodump.tar.gz


  3. Restore MongoDB.
    Go to the extracted folder, cd to every subdir until reaching the Xray directory and run the following command.

    mongorestore /mongodump/xray -u xray -p password --authenticationDatabase xray --db xray --drop --batchSize=1

PostgreSQL

  1. Copy the PostgreSQL backup zip file postgresdump.tar.gz to the new machine.
  2. Extract the PostgreSQL backup file.

    tar -xvf postgresdump.tar.gz


  3. Restore PostgreSQL.

    psql -U xray -f postgresdump xraydb


Step 5: Start the New Xray instance

  1. Remove the authentication provider configuration from the new Xray instance.
    Run the following query in your MongoDB.
    Note: a new authentication provider will be connected later on.

    db.getCollection('configuration').deleteOne({"config_id" : "accessConfig"})
  2. Modify the binary manager collection configuration in MongoDB for the new Xray instance. This step should also be done once for the initial Xray instance.

    1. Run the following query in your MongoDB, to get a list of your Artifactory instances.

      db.getCollection('binary_managers').find({})
    2. Run the following query in your MongoDB, for each of the redundant Artifactory instances, except the selected one you are connecting to this new Xray instance.

      Note: this command requires a non-existant URL to manipulate the new Xray data. These Artifactory connections will be removed once the unnecessary pairings are removed, later on in this procedure.

      db.getCollection('binary_managers').update({"bin_mgr_id" : {"<Redundent-Artifactory-id-to-delete>"}}, {$set : {"bin_mgr_url" : "<non-existing-url-which-not-in-use>"}})
  3. Start the new Xray instance.

  4. Change the Xray base URL.
    In the Xray UI, go to Admin | General, and disable the Xray Base URL.
  5. Validate the Xray URL in Artifactory.
    In the selected Artifactory UI, go to Admin | Advanced | Config Descriptor, and check the xrayConfig.
  6. Enable Xray in Artifactory.
    In the selected Artifactory UI, go to Admin | JFrog Xray, and set Xray to be Enabled.
  7. Connect Xray to your selected authentication provider.
    In the Xray UI, go to Admin | Authentication, and select your Artifactory instance.

Step 6: Additional Xray instances

Repeat steps 3 to 5 for additional Xray instances.

Once you have completed the process of pairing all new Xray instances to their Artifactory instances, go to each Xray instance (Admin | Artifactory) and check that only one Artifactory instance is connected to it.

Continue to upgrade your Artifactory and Xray instances to the new JFrog Platform.

Step 7: Remove unnecessary Artifactory Xray Pairing

Repeat the below steps for each of your Xray instances.

  1. Validate that the new Xray instance is connected to the selected Artifactory instance, as an authentication provider.

    Before continuing to the next step, make sure your Artifactory and Xray are working. You can try to reindex a repository from Artifactory and check to see it was indexed in Xray.

  2. Remove all Artifactory instances connected to Xray, except the one you would like to keep connected to this Xray instance. 
    In the Xray UI, go to Admin | Artifactory, and delete the Artifactory instance(s) to remove. 
    Note: This operation will remove all data for the removed Artifactory instances.
  3. Re-index all required repositories.
    In the Xray UI, go to Admin | Artifactory, click on the authentication provider Artifactory instance and select Index Existing on the repositories to index.




  • No labels
Copyright © 2020 JFrog Ltd.