Elasticsearch to OpenSearch Migration: Rolling Restart

This article demonstrates how to migrate from Elasticsearch to OpenSearch via a rolling restart.

Rolling Restart: Pros and Cons

In the last articles, we described how you can migrate from Elasticsearch to OpenSearch by using the Snapshot/Restore API and by reindexing your data from Elasticsearch to OpenSearch.

In these scenarios, you would run an OpenSearch cluster besides your existing Elasticsearch cluster and migrate the data. After the migration is done, you can switch off Elasticsearch and point all systems to your new OpenSearch cluster.

This is very safe in terms of availability - you always have an operational, running cluster available, and you can re-run the migration as often as needed in case something goes wrong. However, in almost all cases you will need to plan for a (potentially short) outage to make sure your data is identical in both clusters. In addition, using the Reindex or Snapshot/Restore APIs might take a long time, depending on the size of your data.

Within certain boundaries, you can also switch to OpenSearch by a rolling restart or a full cluster restart. This means you migrate your existing and running cluster, including its data, directly to OpenSearch. This is the fastest way of migration since it does not include data export/import at all.

However, it’s also the riskiest, since you make changes to your running production systems. In case something goes wrong, this can leave you with a broken cluster and a potential downtime until the error is fixed.

Also, you will migrate all your data from Elasticsearch to OpenSearch as-is. While in some cases this is exactly what you want, in other cases you might want to take the opportunity to declutter your data and drop indices that are no longer relevant.

Compatibility

Upgrading to OpenSearch via rolling restart means that you temporarily run a mixed cluster where some nodes are still running Elasticsearch, and some nodes already run OpenSearch. Thus, it’s important to check compatibility. Both Elasticsearch and OpenSearch need to be compatible regarding the index data format and the wire protocol.

Generally speaking, it is possible to upgrade via rolling restart if your current Elasticsearch version is between 7.0.0 and 7.10.2, and you are upgrading to OpenSearch 1.x.

For older versions, please upgrade your cluster to Elasticsearch 7.10.2 first.

If you run a version greater than 7.10.2, rolling restarts are not officially supported, but they might work.

There is no direct migration path for Elasicsearch 8.x.

Update your Elasticsearch cluster to 7.10.2

Migrate to OpenSearch 1.x via a rolling restart

Update to the latest OpenSearch version via a rolling restart

Performing a Rolling Restart

Basically, performing a rolling restart means that we take one node down, upgrade it to OpenSearch, and add it to the cluster again until all nodes are upgraded. You can also take more than one node down at a time, but that requires more careful planning to make sure you do not lose any data.

Whenever a node leaves the cluster, Elasticsearch will start to rebalance data in your cluster. While under normal operation this is a good thing, we do not want this during the rolling restart where we remove and add nodes constantly. So the first step is to disable shard allocation:

PUT _cluster/settings
{
 "persistent": {
   "cluster.routing.allocation.enable": "primaries"
 }
}

Next, take down one node in the cluster. How to do that depends on the OS you are running. On a Linux system using systemctl the command would be:

sudo systemctl stop elasticsearch.service

Next, install OpenSearch on the same machine. Make sure that you do not overwrite the Elasticsearch data directory!

Since OpenSearch should use the exact same data as Elasticsearch before, either

Move/copy the data directory from Elasticsearch to OpenSearch, e.g. from /var/lib/elasticsearch/data to /var/lib/opensearch/data

Specify the data directory on opensearch.yml to point to the old location

We prefer the first approach because the latter would leave a directory called “elasticsearch” behind.

Next, compare your elasticsearch.yml with opensearch.yml and make sure at least the following is the same:

cluster id

node id

network host and port

seed_hosts and initial_master_nodes

Now you can start the node running OpenSearch. In an ideal world, the node will join the cluster and the cluster state is still green.

Continue this process on all other nodes in your cluster. Of course, this can also be automated which is especially useful for large clusters.

Finally, enable shard allocation again:

PUT _cluster/settings
{
 "persistent": {
   "cluster.routing.allocation.enable": "all"
 }
}

Where to go Next

If you are unsure if you should migrate at all, read our article about the prerequisites

If you want to use alternative ways of upgrading, see our articles about using the Snapshot/Restore API or the Reindex API