You're viewing version 2.5 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
Migrating from Elasticsearch OSS to OpenSearch
If you want to migrate from an existing Elasticsearch OSS cluster to OpenSearch and find the snapshot approach unappealing, you can migrate your existing nodes from Elasticsearch OSS to OpenSearch.
If your existing cluster runs an older version of Elasticsearch OSS, the first step is to upgrade to version 6.x or 7.x.
Before deciding on the version of Elasticsearch OSS for your upgrade, refer to the Migrating to OpenSearch and limits on the number of nested JSON objects documentation in Breaking changes to see whether the issue will have an impact on your cluster and, therefore, your decisions about upgrades and migration.
Elasticsearch OSS supports two types of upgrades: rolling and cluster restart.
-
Rolling upgrades let you shut down one node at a time for minimal disruption of service.
Rolling upgrades work between minor versions (for example, 6.5 to 6.8) and also support a single path to the next major version (for example, 6.8 to 7.10.2). Performing these upgrades might require intermediate upgrades to arrive at your desired version and can affect cluster performance as nodes leave and rejoin, but the cluster remains available throughout the process.
-
Cluster restart upgrades require you to shut down all nodes, perform the upgrade, and restart the cluster.
Cluster restart upgrades work between minor versions (for example, 6.5 to 6.8) and the next major version (for example, 6.x to 7.10.2). Cluster restart upgrades are faster to perform and require fewer intermediate upgrades, but require downtime.
Migration paths
Elasticsearch OSS version | Rolling upgrade path | Cluster restart upgrade path |
---|---|---|
5.x | Upgrade to 5.6, upgrade to 6.8, reindex all 5.x indexes, upgrade to 7.10.2, and migrate to OpenSearch. | Upgrade to 6.8, reindex all 5.x indexes, and migrate to OpenSearch. |
6.x | Upgrade to 6.8, upgrade to 7.10.2, and migrate to OpenSearch. | Migrate to OpenSearch. |
7.x | Migrate to OpenSearch. | Migrate to OpenSearch. |
If you are migrating an Open Distro for Elasticsearch cluster, we recommend first upgrading to ODFE 1.13 and then migrating to OpenSearch.
Upgrade Elasticsearch OSS
-
Disable shard allocation to prevent Elasticsearch OSS from replicating shards as you shut down nodes:
PUT _cluster/settings { "persistent": { "cluster.routing.allocation.enable": "primaries" } }
-
Stop Elasticsearch OSS on one node (rolling upgrade) or all nodes (cluster restart upgrade).
On Linux distributions that use systemd, use this command:
sudo systemctl stop elasticsearch.service
For tarball installations, find the process ID (
ps aux
) and kill it (kill <pid>
). -
Upgrade the node (rolling) or all nodes (cluster restart).
The exact command varies by package manager, but likely looks something like this:
sudo yum install elasticsearch-oss-7.10.2 --enablerepo=elasticsearch
For tarball installations, extract to a new directory to ensure you do not overwrite your
config
,data
, andlogs
directories. Ideally, these directories should have their own, independent paths and not be colocated with the Elasticsearch application directory. Then set theES_PATH_CONF
environment variable to the directory that containselasticsearch.yml
(for example,/etc/elasticesarch/
). Inelasticsearch.yml
, setpath.data
andpath.logs
to yourdata
andlogs
directories (for example,/var/lib/elasticsearch
and/var/log/opensearch
). -
Restart Elasticsearch OSS on the node (rolling) or all nodes (cluster restart).
On Linux distributions that use systemd, use this command:
sudo systemctl start elasticsearch.service
For tarball installations, run
./bin/elasticsearch -d
. -
Wait for the node to rejoin the cluster (rolling) or for the cluster to start (cluster restart). Check the
_nodes
summary to verify that all nodes are available and running the expected version:# Elasticsearch OSS curl -XGET 'localhost:9200/_nodes/_all?pretty=true' # Open Distro for Elasticsearch with Security plugin enabled curl -XGET 'https://localhost:9200/_nodes/_all?pretty=true' -u 'admin:admin' -k
Specifically, check the
nodes.<node-id>.version
portion of the response. Also check_cat/indices?v
for a green status on all indexes. -
(Rolling) Repeat steps 2–5 until all nodes are using the new version.
-
After all nodes are using the new version, re-enable shard allocation:
PUT _cluster/settings { "persistent": { "cluster.routing.allocation.enable": "all" } }
-
If you upgraded from 5.x to 6.x, reindex all indexes.
-
Repeat all steps as necessary until you arrive at your desired Elasticsearch OSS version.
Migrate to OpenSearch
-
Disable shard allocation to prevent Elasticsearch OSS from replicating shards as you shut down nodes:
PUT _cluster/settings { "persistent": { "cluster.routing.allocation.enable": "primaries" } }
-
Stop Elasticsearch OSS on one node (rolling upgrade) or all nodes (cluster restart upgrade).
On Linux distributions that use systemd, use this command:
sudo systemctl stop elasticsearch.service
For tarball installations, find the process ID (
ps aux
) and kill it (kill <pid>
). -
Upgrade the node (rolling) or all nodes (cluster restart).
-
Extract the OpenSearch tarball to a new directory to ensure you do not overwrite your Elasticsearch OSS
config
,data
, andlogs
directories. -
(Optional) Copy or move your Elasticsearch OSS
data
andlogs
directories to new paths. For example, you might move/var/lib/elasticsearch
to/var/lib/opensearch
. -
Set the
OPENSEARCH_PATH_CONF
environment variable to the directory that containsopensearch.yml
(for example,/etc/opensearch
). -
In
opensearch.yml
, setpath.data
andpath.logs
. You might also want to disable the Security plugin for now.opensearch.yml
might look something like this:path.data: /var/lib/opensearch path.logs: /var/log/opensearch plugins.security.disabled: true
-
Port your settings from
elasticsearch.yml
toopensearch.yml
. Most settings use the same names. At a minimum, specifycluster.name
,node.name
,discovery.seed_hosts
, andcluster.initial_cluster_manager_nodes
. -
(Optional) If you’re actively connecting to the cluster with legacy clients that check for a particular version number, such as Logstash OSS, add a compatibility setting to
opensearch.yml
:compatibility.override_main_response_version: true
-
(Optional) Add your certificates to your
config
directory, add them toopensearch.yml
, and initialize the Security plugin.
-
-
Start OpenSearch on the node (rolling) or all nodes (cluster restart).
For the tarball, run
./bin/opensearch -d
. -
Wait for the OpenSearch node to rejoin the cluster (rolling) or for the cluster to start (cluster restart). Check the
_nodes
summary to verify that all nodes are available and running the expected version:# Security plugin disabled curl -XGET 'localhost:9200/_nodes/_all?pretty=true' # Security plugin enabled curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_nodes/_all?pretty=true'
Specifically, check the
nodes.<node-id>.version
portion of the response. Also check_cat/indices?v
for a green status on all indexes. -
(Rolling) Repeat steps 2–5 until all nodes are using OpenSearch.
-
After all nodes are using the new version, re-enable shard allocation:
PUT _cluster/settings { "persistent": { "cluster.routing.allocation.enable": "all" } }
Upgrade tool
The opensearch-upgrade
tool lets you automate some of the steps in Migrate to OpenSearch, eliminating the need for error-prone manual operations.
The opensearch-upgrade
tool performs the following functions:
- Imports any existing configurations and applies it to the new installation of OpenSearch.
- Installs any existing core plugins.
Limitations
The opensearch-upgrade
tool doesn’t perform an end-to-end upgrade:
- You need to run the tool on each node of the cluster individually as part of the upgrade process.
- The tool doesn’t provide a rollback option after you’ve upgraded a node, so make sure you follow best practices and take backups.
- You must install all community plugins (if available) manually.
- The tool only validates any keystore settings at service start-up time, so you must manually remove any unsupported settings for the service to start.
Using the upgrade tool
To perform a rolling upgrade using the OpenSearch tarball distribution:
Check Migration paths to make sure that the version you’re upgrading to is supported and whether you need to upgrade to a supported Elasticsearch OSS version first.
-
Disable shard allocation to prevent Elasticsearch OSS from replicating shards as you shut down nodes:
PUT _cluster/settings { "persistent": { "cluster.routing.allocation.enable": "primaries" } }
-
On any one of the nodes, download and extract the OpenSearch tarball to a new directory.
-
Make sure the following environment variables are set:
-
ES_HOME
- Path to the existing Elasticsearch installation home.export ES_HOME=/home/workspace/upgrade-demo/node1/elasticsearch-7.10.2
-
ES_PATH_CONF
- Path to the existing Elasticsearch config directory.export ES_PATH_CONF=/home/workspace/upgrade-demo/node1/os-config
-
OPENSEARCH_HOME
- Path to the OpenSearch installation home.export OPENSEARCH_HOME=/home/workspace/upgrade-demo/node1/opensearch-1.0.0
-
OPENSEARCH_PATH_CONF
- Path to the OpenSearch config directory.export OPENSEARCH_PATH_CONF=/home/workspace/upgrade-demo/node1/opensearch-config
-
-
The
opensearch-upgrade
tool is in thebin
directory of the distribution. Run the following command from the distribution home:Make sure you run this tool as the same user running the current Elasticsearch service.
./bin/opensearch-upgrade
-
Stop Elasticsearch OSS on the node.
On Linux distributions that use systemd, use this command:
sudo systemctl stop elasticsearch.service
For tarball installations, find the process ID (
ps aux
) and kill it (kill <pid>
). -
Start OpenSearch on the node:
./bin/opensearch -d.
-
Repeat steps 2–6 until all nodes are using the new version.
-
After all nodes are using the new version, re-enable shard allocation:
PUT _cluster/settings { "persistent": { "cluster.routing.allocation.enable": "all" } }
How it works
Behind the scenes, the opensearch-upgrade
tool performs the following tasks in sequence:
- Looks for a valid Elasticsearch installation on the current node. After it finds the installation, it reads the
elasticsearch.yml
file to get the endpoint details and connects to the locally running Elasticsearch service. If the tool can’t find an Elasticsearch installation, it tries to get the path from theES_HOME
location. - Verifies if the existing version of Elasticsearch is compatible with the OpenSearch version. It prints a summary of the information gathered to the console and prompts you for a confirmation to proceed.
- Imports the settings from the
elasticsearch.yml
config file into theopensearch.yml
config file. - Copies across any custom JVM options from the
$ES_PATH_CONF/jvm.options.d
directory into the$OPENSEARCH_PATH_CONF/jvm.options.d
directory. Similarly, it also imports the logging configurations from the$ES_PATH_CONF/log4j2.properties
file into the$OPENSEARCH_PATH_CONF/log4j2.properties
file. - Installs the core plugins that you’ve currently installed in the
$ES_HOME/plugins
directory. You must install all other third-party community plugins manually. - Imports the secure settings from the
elasticsearch.keystore
file (if any) into theopensearch.keystore
file. If the keystore file is password protected, theopensearch-upgrade
tool prompts you to enter the password.