Upgrade Fusion 3.0.x to 3.1.y

Introduction

This article describes how to perform the following upgrade:

  • From version: Fusion 3.0.x

  • To version: Fusion 3.1.y

Important
Only specific version-to-version upgrade sequences are supported. Some upgrades require multiple steps. For more information, see the supported upgrade sequences.

For Fusion 3.1 and later releases, a migrator is available for upgrading Fusion. During the upgrade process, choose the correct properties file. After downloading and installing the migrator, you can find the properties files in the /opt/fusion/3.0.x/var/upgrade directory (on Unix or MacOS) or the C:\lucidworks\fusion\3.0.x\var\upgrade\ directory (on Windows).

The file names reference the versions you are upgrading from and to. For example:

  • To upgrade 3.0.1 to 3.1.0, use the 3.0.x-3.1.x.properties file.

Migration entails down time and multiple starts and stops of Fusion services. Plan accordingly, especially in terms of disabling external load balancers or monitors that might react adversely to the starts and stops.

Download the latest migrator immediately before upgrading. This helps ensure that the upgrade goes smoothly.

Important
The newer Fusion instance must be newly untarred and never started.

Object migrations

All Fusion 3.0 object types are migrated:

  • Collections

  • Index pipelines

  • Query pipelines

  • Search cluster configurations

  • Schedules

  • Aggregations

  • Datasources

  • Dashboards

  • Parsers

Some objects are transformed for compatibility with the 3.1 set of object types:

  • New 3.1 object types are group, link, task, job, and spark.

  • The aggregation object type has been removed. Aggregation objects are migrated to the spark object type.

  • The schedule object type has been removed. Schedule objects are migrated to the job object type.

  • The new HTML and XML parser stages are added to all default parsers.

  • Any installed JDBC drivers from Fusion 3.0 are uploaded to the 3.1 blob store.

Review known issues

Before upgrading, review the known issues to see whether any of them apply to the circumstances of your upgrade. Some known issues might require actions before upgrading.

Upgrade on Unix (Single Node)

Use this procedure to upgrade Fusion on a single Unix node.

If Fusion is on a single node and either ZooKeeper or Solr is external, then use the procedure in Upgrade on Unix (Multiple Nodes).

To upgrade Fusion on a single Unix node
  1. Download the version of Fusion to which you are upgrading.

    Note
    To avoid a license problem that will cause the upgrade to fail, download Fusion immediately before upgrading.
  2. Download the latest migrator zip file for Unix. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)

  3. Install the newer version of Fusion:

    cd /opt
    mv ~/Downloads/fusion-3.1.y.tar.gz ./
    tar -xf fusion-3.1.y.tar.gz

    For example, if Fusion is currently installed in /opt/fusion/3.0.x, then change your working directory to /opt/ and extract the file there. Don’t run the new version of Fusion yet.

  4. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.

  5. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from http://lucidworks.com/connectors/ and place them in apps/connectors/bootstrap-plugins for the new deployment.

    Alternatively, you can use the UI or API to install new connectors after the migration is complete.

  6. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion/3.0.x/data/solr. If there isn’t sufficient disc space, free up space before proceeding.

  7. Create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively (using the full path).

    export FUSION_OLD="/opt/fusion/3.0.x"
    export FUSION_NEW="/opt/fusion/3.1.y"

    For example, when upgrading from Fusion 3.0.1 to 3.1.0:

    export FUSION_OLD="/opt/fusion/3.0.1"
    export FUSION_NEW="/opt/fusion/3.1.0"
  8. Create this directory:

    mkdir $FUSION_OLD/var/upgrade
  9. Install the migrator:

    tar -zxv -C $FUSION_OLD/var/upgrade --strip-components=1 -f fusion-migrator.tar.gz
  10. Ensure that the old version of Fusion is not running:

    $FUSION_OLD/bin/fusion stop
  11. Run migrator.jar:

    java -jar $FUSION_OLD/var/upgrade/migrator.jar -f $FUSION_OLD -t $FUSION_NEW -p 3.0.x-3.1.x.properties

    The end of the output from a successful migration looks like this:

      "status" : "Import was completed"
    }
    2018-04-10T11:16:53,961 - INFO  [main:Main@592] - Validating import with full export from target system
    2018-04-10T11:16:53,963 - INFO  [main:ObjectExportImportManager@74] - Exporting objects for testing migration: http://127.0.0.1:8765/api/v1/objects/export?filterPolicy=none
    2018-04-10T11:16:55,035 - INFO  [main:ObjectExportImportManager@78] - Exporting objects finished: HTTP/1.1 200 OK
    2018-04-10T11:16:55,035 - INFO  [main:Main@596] - Stopping new Fusion services
    2018-04-10T11:16:55,035 - INFO  [main:ServicesManager@240] - Starting process: java -jar /Users/jeffthomas/fusion/3.1.4/apps/lucidworks-agent.jar stop --no-agent
    2018-04-10T11:16:57,101 - INFO  [main:Iterator@116] - Successfully stopped ui (process ID 12957)
    2018-04-10T11:16:58,755 - INFO  [main:Iterator@116] - Successfully stopped connectors (process ID 12710)
    2018-04-10T11:17:00,518 - INFO  [main:Iterator@116] - Successfully stopped api (process ID 12596)
    2018-04-10T11:17:02,094 - INFO  [main:Iterator@116] - Successfully stopped solr (process ID 12593)
    2018-04-10T11:17:03,140 - INFO  [main:Iterator@116] - Successfully stopped zookeeper (process ID 12571)
    Tip
    After migration, you can find details about the results in the fusion/3.0.x/var/upgrade/tmp directory. If the migration produces unexpected results, the files in this directory are helpful for troubleshooting.
  12. Run the new version of Fusion (all services defined in fusion.properties):

    $FUSION_NEW/bin/fusion start
  13. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:

    1. Clear your browser’s cache.

      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.

    2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).

    3. Log in.

    4. Navigate to admin > About Fusion.

      The About Fusion panel should display the newer Fusion release number.

  14. Validate the installation.

    • Ensure that all connectors were installed automatically during the upgrade. From the Fusion launcher, click Devops > Home Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.

    • Ensure that all customizations you made in the former version of Fusion are present in the new one.

    Tip
    When you are satisfied with the migration and you have backed up the fusion/3.0.x/ directory, you can rm -fr fusion/3.0.x/ to remove the older version of Fusion.

Upgrade on Unix (Multinode)

Use this procedure to upgrade Fusion on multiple Unix nodes.

Also use this procedure if Fusion is on a single node and either ZooKeeper or Solr is external.

To upgrade Fusion on Unix

Perform the steps in this procedure on the indicated nodes on which Fusion is running. If Solr and/or ZooKeeper instances are also running on other nodes (without Fusion), you don’t need to do anything on the external Solr and/or ZooKeeper instance nodes.

Important
For every step on multiple nodes, ensure that the step completes on all Fusion nodes before going to the next step. There is the notion of a "main node" during the migration process. This node will be used for certain centralized migration activities that do not need to be done on every node, such as downloading connectors that are then uploaded to blob storage that is shared by all, etc. Just pick one of your Fusion nodes to be the "main node"; there’s no special requirement as to which one you pick.
Perform the following tasks on all Fusion nodes:
  1. Download the version of Fusion to which you are upgrading.

  2. Download the latest migrator zip file for Unix. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)

  3. Install the newer version of Fusion:

    cd /opt
    mv ~/Downloads/fusion-3.1.y.tar.gz ./
    tar -xf fusion-3.1.y.tar.gz

    For example, if Fusion is currently installed in /opt/fusion/3.0.x, then change your working directory to /opt/ and extract the file there. Don’t run the new version of Fusion yet.

  4. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.

  5. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from http://lucidworks.com/connectors/ and place them in apps/connectors/bootstrap-plugins for the new deployment.

    Alternatively, you can use the UI or API to install new connectors after the migration is complete.

  6. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion/3.0.x/data/solr. If there isn’t sufficient disc space, free up space before proceeding.

  7. Create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively (using the full path).

    export FUSION_OLD="/opt/fusion/3.0.x"
    export FUSION_NEW="/opt/fusion/3.1.y"

    For example, when upgrading from Fusion 3.0.1 to 3.1.0:

    export FUSION_OLD="/opt/fusion/3.0.1"
    export FUSION_NEW="/opt/fusion/3.1.0"
  8. Create an environment variable for the migrator properties file to use:

    export PROPERTIES=3.0.x-3.1.x.properties
  9. Create this directory:

    mkdir $FUSION_OLD/var/upgrade
  10. Install the migrator:

    tar -zxv -C $FUSION_OLD/var/upgrade --strip-components=1 -f fusion-migrator.tar.gz
  11. Start all Fusion services for the old version of Fusion:

    $FUSION_OLD/bin/fusion start
  12. (On the main Fusion node) Run the migrator with the argument -1:

    java -jar $FUSION_OLD/var/upgrade/migrator.jar -f $FUSION_OLD -t $FUSION_NEW -p $PROPERTIES -1

    This message indicates that the step finished successfully:

    Step 1 finished successfully.
  13. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:

  14. (On all Fusion nodes) Run the migrator with the argument -2:

    java -jar $FUSION_OLD/var/upgrade/migrator.jar -f $FUSION_OLD -t $FUSION_NEW -p $PROPERTIES -2

    This message indicates that the step finished successfully:

    Step 2 finished successfully.
  15. (On all Fusion nodes) Stop ZooKeeper for the old version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):

    $FUSION_OLD/bin/zookeeper stop
  16. (On the main Fusion node) Run the migrator with the argument -3:

    java -jar $FUSION_OLD/var/upgrade/migrator.jar -f $FUSION_OLD -t $FUSION_NEW -p $PROPERTIES -3
    Note
    Depending on the size of your Solr index, this step can take a long time (for example, multiple tens of minutes).

    This message indicates that the step finished successfully:

    Step 3 finished successfully.
  17. (On all Fusion nodes except the main node; skip this step for a single-node upgrade) Run the migrator with the argument -7:

    java -jar $FUSION_OLD/var/upgrade/migrator.jar -f $FUSION_OLD -t $FUSION_NEW -p $PROPERTIES -7

    This message indicates that the step finished successfully:

    Step 7 finished successfully.
  18. (On all Fusion nodes) Start ZooKeeper for the new version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):

    $FUSION_NEW/bin/zookeeper start
  19. (On the main Fusion node) Run the migrator with the argument -4:

    java -jar $FUSION_OLD/var/upgrade/migrator.jar -f $FUSION_OLD -t $FUSION_NEW -p $PROPERTIES -4

    This message indicates that the step finished successfully:

    Step 4 finished successfully.
  20. (On all Fusion nodes) Start Solr for the new Fusion version:

    $FUSION_NEW/bin/solr start
  21. (On the main Fusion node) Run a script to remove all old plugins from the blob store. Replace solr-address and solr-port as appropriate (as shown in the example):

    java -cp "$FUSION_OLD/var/upgrade/jython-standalone-{jython}.jar:$FUSION_OLD/var/upgrade/migrator.jar" org.python.util.jython "$FUSION_OLD/var/upgrade/transformations/manual_delete_old_plugin_blobs.py" --solr-address solr-address --solr-port solr-port

    For example:

    java -cp "$FUSION_OLD/var/upgrade/jython-standalone-{jython}.jar:$FUSION_OLD/var/upgrade/migrator.jar" org.python.util.jython "$FUSION_OLD/var/upgrade/transformations/manual_delete_old_plugin_blobs.py" --solr-address localhost --solr-port 8983

    This message indicates that plugins were deleted successfully:

    Deleted old plugin blobs from solr <?xml version="1.0" encoding="UTF-8"?>
    <response>
    
    <lst name="responseHeader">
      <int name="status">0</int>
      <int name="QTime">246</int>
    </lst>
    </response>
    Old connector plugin blobs were deleted successfully.
  22. (On all Fusion nodes) Start all Fusion services for the new version of Fusion:

    $FUSION_NEW/bin/fusion start
  23. (On the main Fusion node) Run the migrator with the argument -5:

    java -jar $FUSION_OLD/var/upgrade/migrator.jar -f $FUSION_OLD -t $FUSION_NEW -p $PROPERTIES -5

    This message indicates that the step finished successfully:

    Step 5 finished successfully.
  24. (On the main Fusion node) Run the migrator with the argument -6:

    java -jar $FUSION_OLD/var/upgrade/migrator.jar -f $FUSION_OLD -t $FUSION_NEW -p $PROPERTIES -6

    This message indicates that the step finished successfully:

    Step 6 finished successfully.
    Tip
    After migration, you can find details about the results in the fusion/3.0.x/var/upgrade/tmp directory. If the migration produces unexpected results, the files in this directory are helpful for troubleshooting.
  25. (On the main Fusion node) Restart the new version of Fusion (all services defined in fusion.properties):

    $FUSION_NEW/bin/fusion restart
  26. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:

    1. Clear your browser’s cache.

      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.

    2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).

    3. Log in.

    4. Navigate to admin > About Fusion.

      The About Fusion panel should display the newer Fusion release number.

  27. Validate the installation.

    • Ensure that all connectors were installed automatically during the upgrade. From the Fusion launcher, click Devops > Home Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.

    • Ensure that all customizations you made in the former version of Fusion are present in the new one.

    Tip
    When you are satisfied with the migration and you have backed up the fusion/3.0.x/ directory, you can rm -fr fusion/3.0.x/ to remove the older version of Fusion (on all Fusion nodes).

Upgrade on Windows

Use this procedure to upgrade Fusion on a single Windows node or multiple Windows nodes. If there is a single node, perform all steps on that node unless otherwise indicated.

To upgrade Fusion on Windows

Perform the steps in this procedure on the indicated nodes on which Fusion is running. If Solr and/or ZooKeeper instances are also running on other nodes (without Fusion), you don’t need to do anything with the external Solr and/or ZooKeeper instances.

Important
If you are upgrading Fusion on multiple nodes, then, for every step on multiple nodes, ensure that the step completes on all Fusion nodes before going to the next step. There is the notion of a "main node" during the migration process. This node will be used for certain centralized migration activities that do not need to be done on every node, such as downloading connectors that are then uploaded to blob storage that is shared by all, etc. Just pick one of your Fusion nodes to be the "main node"; there’s no special requirement as to which one you pick.
Perform the following tasks on all Fusion nodes:
  1. Download the version of Fusion to which you are upgrading.

  2. Download the latest migrator zip file for Windows. (Do this now, even if you have downloaded the migrator before, to ensure that you have the latest version.)

  3. Move the fusion-3.1.y.zip file to the directory that contains the fusion\ directory.

    For example, if Fusion is installed in C:\lucidworks\fusion\3.0.x, then move the file to C:\lucidworks.

  4. Unzip the fusion-3.1.y.zip file. Don’t run the new version of Fusion yet.

  5. (If there are custom jar files) If your deployment has custom jar files, add them to the new Fusion deployment.

  6. (If you are adding new connectors) If you want your new deployment to use connectors that are not in the current deployment, you can add them now. Download the connector zip files from http://lucidworks.com/connectors/ and place them in apps\connectors\bootstrap-plugins for the new deployment.

    Alternatively, you can use the UI or API to install new connectors after the migration is complete.

  7. Verify that there is sufficient disk space for a second copy of the Solr index directory, fusion\3.0.x\data\solr. If there isn’t sufficient disc space, free up space before proceeding.

  8. Open a Command Prompt window and create FUSION_OLD and FUSION_NEW environment variables that point to the old and new Fusion installation directories respectively. For example:

    set FUSION_OLD=C:\lucidworks\fusion\3.0.1
    set FUSION_NEW=C:\lucidworks\fusion\3.1.0
  9. Create an environment variable for the migrator properties file to use:

    set PROPERTIES=3.0.x-3.1.x.properties
  10. Create a fusion\3.0.x\var\upgrade directory.

  11. Unzip the migrator zip file, and move the contents of the extracted folder to fusion\3.0.x\var\upgrade.

  12. Start all Fusion services for the old version of Fusion:

    %FUSION_OLD%\bin\fusion.cmd start
Perform the following tasks on the indicated nodes:
  1. (On the main Fusion node) Run the migrator with the argument -1:

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" -f "%FUSION_OLD%" -t "%FUSION_NEW%" -p "%PROPERTIES%" -1

    This message indicates that the step finished successfully:

    Step 1 finished successfully.
  2. (On all Fusion nodes) Stop the old versions of Fusion services and Solr; but not ZooKeeper:

  3. (On all Fusion nodes) Run the migrator with the argument -2:

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" -f "%FUSION_OLD%" -t "%FUSION_NEW%" -p "%PROPERTIES%" -2

    This message indicates that the step finished successfully:

    Step 2 finished successfully.
  4. (On all Fusion nodes) Stop ZooKeeper for the old version of Fusion (unless you are using an external ZooKeeper instance, in which case you can ignore this step):

    %FUSION_OLD%\bin\zookeeper.cmd stop
  5. (On the main Fusion node) Run the migrator with the argument -3:

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" -f "%FUSION_OLD%" -t "%FUSION_NEW%" -p "%PROPERTIES%" -3
    Note
    Depending on the size of your Solr index, this step can take a long time (for example, multiple tens of minutes).

    This message indicates that the step finished successfully:

    Step 3 finished successfully.
  6. (On all Fusion nodes except the main node; skip this step for a single-node upgrade) Run the migrator with the argument -7:

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" -f "%FUSION_OLD%" -t "%FUSION_NEW%" -p "%PROPERTIES%" -7

    This message indicates that the step finished successfully:

    Step 7 finished successfully.
  7. (On all Fusion nodes) Start ZooKeeper for the new version of Fusion (unless you are only using an external ZooKeeper instance, in which case you can ignore this step):

    %FUSION_NEW%\bin\zookeeper.cmd start
  8. (On the main Fusion node) Run the migrator with the argument -4:

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" -f "%FUSION_OLD%" -t "%FUSION_NEW%" -p "%PROPERTIES%" -4

    This message indicates that the step finished successfully:

    Step 4 finished successfully.
  9. (On all Fusion nodes) Start Solr for the new Fusion version:

    %FUSION_NEW%\bin\solr.cmd start
  10. (On the main Fusion node) Run a script to remove all old plugins from the blob store. Replace solr-address and solr-port as appropriate (as shown in the example):

    java -cp "%FUSION_OLD%\var\upgrade\jython-standalone-{jython}.jar;%FUSION_OLD%\var\upgrade\migrator.jar" org.python.util.jython "%FUSION_OLD%\var\upgrade\transformations\manual_delete_old_plugin_blobs.py" --solr-address solr-address --solr-port solr-port

    For example:

    java -cp "%FUSION_OLD%\var\upgrade\jython-standalone-{jython}.jar;%FUSION_OLD%\var\upgrade\migrator.jar" org.python.util.jython "%FUSION_OLD%\var\upgrade\transformations\manual_delete_old_plugin_blobs.py" --solr-address localhost --solr-port 8983

    This message indicates that plugins were deleted successfully:

    Deleted old plugin blobs from solr <?xml version="1.0" encoding="UTF-8"?>
    <response>
    
    <lst name="responseHeader">
      <int name="status">0</int>
      <int name="QTime">246</int>
    </lst>
    </response>
    Old connector plugin blobs were deleted successfully.
  11. (On all Fusion nodes) Start all Fusion services for the new version of Fusion:

    %FUSION_NEW%\bin\fusion.cmd start
  12. (On the main Fusion node) Run the migrator with the argument -5:

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" -f "%FUSION_OLD%" -t "%FUSION_NEW%" -p "%PROPERTIES%" -5

    This message indicates that the step finished successfully:

    Step 5 finished successfully.
  13. (On the main Fusion node) Run the migrator with the argument -6:

    java -jar "%FUSION_OLD%\var\upgrade\migrator.jar" -f "%FUSION_OLD%" -t "%FUSION_NEW%" -p "%PROPERTIES%" -6

    This message indicates that the step finished successfully:

    Step 6 finished successfully.
    Tip
    After migration, you can find details about the results in the fusion\3.0.x\var\upgrade\tmp directory. If the migration produces unexpected results, the files in this directory are helpful for troubleshooting.
  14. (On all Fusion nodes) Restart all Fusion services for the new version of Fusion:

    %FUSION_NEW%\bin\fusion.cmd restart
  15. Log into the Fusion UI (your admin password is the same as for the old installation), and confirm the release number of the new version of Fusion:

    1. Clear your browser’s cache.

      Otherwise, you might inadvertently access a cached version of the old Fusion UI and see inconsistent behavior.

    2. In a browser, open the Fusion UI at http://localhost:8764/ (replace localhost with your server name or IP address if necessary).

    3. Log in.

    4. Navigate to admin > About Fusion.

      The About Fusion panel should display the newer Fusion release number.

  16. Validate the installation.

    • Ensure that all connectors were installed automatically during the upgrade. From the Fusion launcher, click Devops > Home Home > Blobs. If any connectors are missing from the list, click Add > Connector Plugin and install them manually.

    • Ensure that all customizations you made in the former version of Fusion are present in the new one.

    Tip
    When you are satisfied with the migration and you have backed up the fusion\3.0.x directory, you can remove the older version of Fusion by removing that directory (on all Fusion nodes).