Upgrade your Elasticsearch database if you already have an Elasticsearch database up and running, either as part of an Tridion Docs instance, an Tridion Sites instance that you are upgrading, or both. Depending on your setup, the tasks to perform differ. In any case, the version of Elasticsearch to use has changed. You always need to install the new Elasticsearch version alongside the old one, run one or two migration scripts, and switch to the new microservices and Elasticsearch instance.
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 both of the following is true:
- You have Tridion Docs installed with its Elasticsearch search feature
- You have Tridion Sites installed with the Experience Optimization feature set up, which uses Elasticsearch
Procedure
- Install the currently supported version of Elasticsearch alongside your existing one. If you install your new Elasticsearch instance in the same environment as your existing one, make sure to configure a different set of ports for the new instance.
- In the elasticsearch.yml configuration file of your new Elasticsearch 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 Elasticsearch instance
- a property called transport.tcp.port set to the transport port of your new Elasticsearch instance
- Start your new Elasticsearch instance.
- Kindly tell your users that until you have finalized the upgrade to the new microservices, including Elasticsearch, they must not publish content. That is, there should now be a publishing freeze.
- If you have Tridion Sites installed with the Experience Optimization feature set up, inform your users that using Experience Optimization Powershell cmdlets for managing Regions and trigger types will not work until the upgrade is completed, because those cmdlets do not work with the new Elasticsearch version. After your upgrade has completed, if you are using the cmdlets on a different machine, do a fresh import of the new set of Powershell cmdlets included with SDL Tridion Sites 9.5. The old cmdlets will not work anymore.
- If you have Tridion Sites installed with the Experience Optimization feature set up, on your SDL Tridion Sites 9.5 installation media, navigate to the folder Content Delivery\roles\xo\elasticsearch\upgrade\.
- If you have Tridion Sites installed with the Experience Optimization feature set up, open a Powershell prompt and enter the following command (but do not yet press Enter):
.\Migrate-XO-Elasticsearch-Data.ps1 -OldElasticInstanceBaseUrl OLDBASEURL -NewElasticInstanceBaseUrl 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 Elasticsearch instance, for example, https://mynewinstance.com:9220
For example, your command may look as follows:
.\Migrate-XO-Elasticsearch-Data.ps1 -OldElasticInstanceBaseUrl http://localhost:9200 -NewElasticInstanceBaseUrl http://localhost:9220
- After the command, also specify the following command line parameter-value pairs as needed:
-OldElasticInstanceUser "OLDUSER"
-OldElasticInstancePassword "OLDPASSWORD"
-NewElasticInstanceBaseUrl "NEWBASEURL"
-NewElasticInstanceUser "NEWUSER"
-NewElasticInstancePassword "NEWPASSWORD"
-IndexPrefix "CUSTOMPREFIX"
where:
- OLDUSER is the username that lets you access the old Elasticsearch instance (defaults to
elastic if omitted)
- OLDPASSWORD is the password for that user (defaults to
changeme if omitted)
- NEWUSER is the username that lets you access the new Elasticsearch instance (defaults to
elastic if omitted)
- NEWPASSWORD is the password for that user (defaults to
changeme if omitted)
- CUSTOMPREFIX is your custom index prefix (if you use one).
- Press Enter to run the script.
The script prompts you to provide the URLs for both the old and the new Elasticsearch instances. The script then migrates your Experience Optimization data from your old Elasticsearch instance to your new one, and updates the indexes.
- If you have Tridion Docs installed with its Elasticsearch search feature, on your SDL Tridion Sites 9.5 installation media, navigate to the folder Content Delivery\roles\iq\elasticsearch\upgrade\.
- If you have Tridion Docs installed with its Elasticsearch search feature, open a Powershell prompt and enter the following command (but do not yet press Enter):
.\Migrate-IQ-Elasticsearch-Data.ps1 -OldElasticInstanceBaseUrl OLDBASEURL -NewElasticInstanceBaseUrl 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 Elasticsearch instance, for example, https://mynewinstance.com:9220
For example, your command may look as follows:
.\Migrate-IQ-Elasticsearch-Data.ps1 -OldElasticInstanceBaseUrl http://localhost:9200 -NewElasticInstanceBaseUrl http://localhost:9220
- After the command, also specify the following command line parameter-value pairs as needed:
-OldElasticInstanceUser "OLDUSER"
-OldElasticInstancePassword "OLDPASSWORD"
-NewElasticInstanceBaseUrl "NEWBASEURL"
-NewElasticInstanceUser "NEWUSER"
-NewElasticInstancePassword "NEWPASSWORD"
-IndexPrefix "CUSTOMPREFIX"
where:
- OLDUSER is the username that lets you access the old Elasticsearch instance (defaults to
elastic if omitted)
- OLDPASSWORD is the password for that user (defaults to
changeme if omitted)
- NEWUSER is the username that lets you access the new Elasticsearch instance (defaults to
elastic if omitted)
- NEWPASSWORD is the password for that user (defaults to
changeme if omitted)
- CUSTOMPREFIX is your custom index prefix (if you use one).
- Press Enter to run the script.
The script prompts you to provide the URLs for both the old and the new Elasticsearch instances. The script then migrates your search data from your old Elasticsearch instance to your new one, and updates the indexes.
- Remove the reindex.remote.whitelist property from the elasticsearch.yml configuration file of your new Elasticsearch instance.
- When you have finished upgrading your new microservices, switch to the new services and the new Elasticsearch.
- If you are using the Experience Optimization cmdlets on a different machine, import the new set of Powershell cmdlets. Kindly tell your users they can use these new cmdlets.
- Kindly tell your users that the publishing freeze is now over. They can publish again.