Documentation Center

Migrating from Elasticsearch to OpenSearch

Migrate from your Elasticsearch database to an OpenSearch database if you already have an Elasticsearch database up and running, either as part of a Tridion Docs instance, a Tridion Sites instance, or both. Depending on your setup, the tasks to perform differ. To perform the migration, perform a complete reindex of your Elasticsearch indexes in a new OpenSearch cluster. RWS provides migration scripts to help you with the migration.

Before you begin

Before you start this task, make sure that your Elasticsearch instances have a cluster health state set to green. Refer to the Elasticsearch documentation for more information.

About this task

If you already have an Elasticsearch database, one or more of the following is true:
  • You have Tridion Docs installed with its Elasticsearch search feature
  • You have Tridion Sites installed with its Elasticsearch search feature
  • You have Tridion Sites installed with the Experience Optimization feature set up, which uses Elasticsearch
Also note that your Elasticsearch database must have the following plugins installed:
  • Ingest Attachment Processor Plugin
  • ICU Analysis Plugin

Procedure

  1. Install OpenSearch alongside Elasticsearch. If you install OpenSearch in the same environment as your existing one, make sure to configure a different set of ports for it.
  2. In the opensearch.yml configuration file of your OpenSearch instance, ensure the presence of the following property-value pairs:
    • a property called reindex.remote.whitelist set to the URL of your old Elasticsearch instance, consisting of a host name, colon and port number, for example, example.com:9200
    • a property called http.port set to the general port of your new OpenSearch instance
    • a property called transport.tcp.port set to the transport port of your new OpenSearch instance
  3. Start your new OpenSearch instance.
  4. Kindly tell your users that until you have finalized the upgrade to the new microservices, including the migration from Elasticsearch to OpenSearch, they must not publish content. That is, there should now be a publishing freeze.
  5. If you have Tridion Docs or Tridion Sites installed with the Elasticsearch search feature, then on your Tridion Docs 15 installation media, navigate to the folder Content Delivery\roles\iq\opensearch\upgrade\.
  6. If you have Tridion Docs or Tridion Sites installed with the Elasticsearch search feature, open a Powershell prompt and enter the following command (but do not yet press Enter):
    .\Migrate-IQ-ES-to-OS.ps1 -OldElasticInstanceBaseUrl OLDBASEURL -NewOpenSearchInstanceBaseUrl NEWBASEURL
    where:
    • OLDBASEURL is the base URL of your current Elasticsearch instance, for example, https://myinstance.com:9200
    • NEWBASEURL is the base URL of your new OpenSearch instance, for example, https://mynewinstance.com:9220
    For example, your command may look as follows:
    .\Migrate-IQ-ES-to-OS.ps1 -OldElasticInstanceBaseUrl http://localhost:9200 -NewOpenSearchInstanceBaseUrl http://localhost:9220
  7. Specify additional parameter-value pairs as needed.
  8. Press Enter to run the script.
    The script prompts you to provide the URLs for both the old Elasticsearch instance and the new OpenSearch instance. The script then migrates your search data from your old Elasticsearch instance to your new OpenSearch instance, and updates the indexes.
  9. Remove the reindex.remote.whitelist property from the opensearch.yml configuration file of your new OpenSearch instance instance.
  10. When you have finished upgrading your new microservices, switch to the new services and to the new OpenSearch instance.
  11. Kindly tell your users that the publishing freeze is now over. They can publish again.

Results

The script has now migrated your Elasticsearch indexes and turned them into OpenSearch indexes. Any metadata fields have been given a data type, which can be queried using the Public Content API. In previous indexes, text field values that look like a date (say, a text field value "2022-12-22T15:00:00+0000") had been stored as a date field by Elasticsearch. The migration creates two copies of such a field, one with a date type and one with a text type. When you republish an item with such a field, the data type you have marked it with will determine in which field the value will be stored.