Prepare a new index

To begin the upgrade process, an upgraded version of a site’s Elasticsearch index must be prepared to allow for testing.

Elasticsearch index preparation is per-environment. Perform the upgrade process and related testing on all non-production environments first. The upgrade process on a non-production environment might reveal actions that are necessary to prepare the production environment for a smooth upgrade to Elasticsearch 8.

Access

To prepare an Elasticsearch index, you must have sufficient access to the VIP Dashboard for the application to which an environment belongs. This requires you to have either an App admin role for the application or an Org admin role.

Read more about user access for the VIP Dashboard

Once you are logged in to the VIP Dashboard for the correct application:

1. Select “Integrations” from the sidebar navigation at the left of the screen.
   • Integration activation is environment-specific. If needed, select a different environment (e.g., staging, develop) from the dropdown located at the upper left of the VIP Dashboard application view.
2. Locate Enterprise Search in the list of Integrations in the App Integrations panel.
3. On the right-hand side of the Enterprise Search row, select the linked text with the value “Configure” to access the Configure Integration panel.

Read more about the Configure Integration panel

Prepare the Elasticsearch index for upgrade

In the section labeled “Elasticsearch“ a notice titled “Version Upgrade Required” is displayed if the upgrade process has not yet begun for the environment.

1. Select the button labeled “Prepare Elasticsearch Indexes For Upgrade” to initiate the preparation of the existing Elasticsearch index for an upgrade. This action will copy your existing Elasticsearch index in the Elasticsearch 7 cluster and copy (i.e. re-index) it to the new Elasticsearch 8 cluster.

Your request for index preparation will be queued, and you will receive an Important Alerts notification when preparation is complete.

Read more about Important Alerts

You can close the browser window and return to the Configure Integration panel for Enterprise Search after you receive a notification that preparation is complete.

The actions that occur during the preparation step differ depending on the type of environment:

• For a non-production environment, the entire upgrade process is completed and the environment will be upgraded to Elasticsearch 8 as a result.
• For production environments, the upgrade process will pause after the new Elasticsearch 8 index is prepared. Your production environment will function in a “double-indexing” mode that simultaneously sends all write queries (e.g. indexing, updating or deleting documents) to both the Elasticsearch 7 and the Elasticsearch 8 clusters. This enables testing to be performed on a production environment before completing the Elasticsearch 8 upgrade.

What to expect

During the preparation process, your site’s search functionality will continue to perform as usual.

The amount of time required to complete the preparation step will vary. Typically a small Elasticsearch index will complete preparation in minutes, while large or complex indexes could require several hours.

If for any reason the preparation step fails, an Important Alerts notification will be sent to notify you of the failure. The VIP Team will also be notified of the failure, and they will automatically restart the preparation process after resolving the underlying issue.

After the preparation step is successfully completed for an environment, the new Elastiscsearch 8 index is ready for testing.