Upgrading Elasticsearch

If you are upgrading to Relativity Server 2022 and your environment uses a version of Elasticsearch below 6.x to store audits, you have the option to upgrade to Elasticsearch 7.x. Relativity versions below Server 2021 are limited to Elasticsearch 6.x, per the compatibility matrix below. We recommend first upgrading Relativity and then upgrading Elasticsearch using one of the workflows on this topic.

The following table breaks down Elasticsearch compatibility per Relativity version:

Relativity version Elastic version
10.1 and lower 2.3.3
10.2 2.3.3 and 6.x
10.3 2.3.3 and 6.x
Server 2021 2.3.3 and 6.x and 7.12.1
Server 2022 2.3.3 and 6.x and 7.12.1

Pre-upgrade steps

  1. Download the IncrementalUpgrade7x.zip from the Relativity Community in the Misc. Customer Support Files library under the Files tab. This package has all the scripts required for the upgrade. We recommend starting off with a new cluster with a number of nodes equal to the number of primary and replica shards in your cluster. For example, if your current cluster has 1 primary and 1 replica shard, your cluster requires 2 nodes. These nodes should be the same size as the nodes on the existing cluster, ensuring the indexes from the node have enough room to be allocated onto the new destination cluster.

    Note: You can find the number_of_shards and number_of_replicas count using the Elastic API. Send a GET request to the following URL: (https://<host>:<port>/_template/audit).

  2. Whitelist the source cluster so that it can be re-indexed into the destination cluster:
    1. Open the elasticsearch.yml (<elastic_install_directory_path>\RelativityDataGrid\elasticsearch-main\config) file from a node where you are running the re-index script.
    2. Update the reindex.remote.whitelist parameter to allow list the endpoint of the source cluster. For example:
      reindex.remote.whitelist: emttest:9200

      You can set this to a comma delimited list of allowed remote host and port combinations (e.g. otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*). You must configure the whitelist on all nodes.

    3. Re-start the cluster. You only need to restart the cluster the first time you complete this step.
  3. If you do not already have it installed and configured, install the latest version of Python - 3.7.4 and select Add Python 3.7 to PATH during the installation.
    1. Run Powershell as administrator, and then navigate to the <python_install_directory_path>\Python37\Scripts folder where Python is installed.
    2. Run the following to install the package
      .\pip3 install elasticsearch
  4. Ensure you have SQL access at the EDDS level to run SQL scripts.

Upgrading from Elasticsearch 2.3.3 to 7.x

Upgrading to Elasticsearch 7.x consists of two steps:

  1. Re-indexing into the new cluster.
  2. Running the incremental upgrade script.

Re-indexing into the new cluster

In order to upgrade from Elasticsearch 2.3.3 to 7.x, you must incrementally move all the workspace indexes on the existing 2.3.3 cluster to the newly provisioned 7.x cluster. You can do this in one of three ways.

Deleting the source index

If you didn't set the --delete_source_indices "True" parameter to automatically delete the indexes on the source cluster, you must manually delete the indexes using the Elastic API.

Running the incremental upgrade script

To complete the upgrade, run the incremental_upgrade_setup.sql script (\IncrementalUpgrade\sql) from a SQL editor at the EDDS level. This script sets up the Audit application to write and read from two endpoints during the upgrade.

Edit the following variables in the script:

  • @primaryShards - enter the number of primary shards. The default value is 1.
  • @replicaShards - enter the number of primary shards. The default value is 1.
  • @previousAuditDataGridEndpoint - enter the previous Audit endpoint. For example, https://2xendpoint:9200..
  • @previousElasticSearchMajorVersion - enter the previous Elasticsearch major version. For example, if you are on Elasticsearch 2.3.3, enter 2.
  • @currentAuditDataGridEndpoint - enter the current Audit endpoint. For example, https://6xendpoint:9200.
  • @currentElasticSearchMajorVersion - enter the current Elasticsearch major version. In this case, enter 6.
  • @workspaceIds - enter a comma separated list of the Artifact IDs of the workspaces identified for upgrade.

Rolling upgrades

You have the option of performing a rolling upgrade of Elastic, specifically from versions 6.6.0 and 6.8.13 directly to 6.8.22 or 7.12.1, by accessing the rolling upgrade .exe files from the Relativity Community.

Those files can be found here:

Updating the instance setting

Once you complete the upgrade, you must also update the DataGridEndpointinstance setting with the endpoint for the Elasticsearch cluster. For example, https://6xendpoint:9200. This value is required to activate Data Grid operation for the Relativity instance.