diff --git a/docs/migrate/docker-migrate.md b/docs/migrate/docker-migrate.md new file mode 100644 index 00000000..a6fea90d --- /dev/null +++ b/docs/migrate/docker-migrate.md @@ -0,0 +1,14 @@ +--- +layout: default +title: Docker migration +parent: Migrate to OpenSearch +nav_order: 25 +--- + +# Docker migration + +If you use Docker images, we highly recommend that you perform what amounts to a [cluster restart upgrade](../upgrade-migrate/). Update your cluster configuration with new images, new settings, and new environment variables. Then stop and start the cluster. This process requires downtime, but takes very few steps. + +If you use a container orchestration system like Kubernetes and want to avoid downtime, think of the process not as an upgrade of each node, but as a decommissioning and replacement of each node. Gradually add OpenSearch nodes to the cluster while removing Elasticsearch OSS nodes. + +The most important step is to leave your data volumes intact. **Don't** run `docker-compose down -v` or any similar command. diff --git a/docs/migrate/index.md b/docs/migrate/index.md new file mode 100644 index 00000000..770bb3d3 --- /dev/null +++ b/docs/migrate/index.md @@ -0,0 +1,11 @@ +--- +layout: default +title: Migrate to OpenSearch +nav_order: 6 +has_children: true +has_toc: true +--- + +# Migrate to OpenSearch + +The process of migrating from Elasticsearch OSS (including Open Distro for Elasticsearch) to OpenSearch varies depending on your current version of Elasticsearch OSS, install type, tolerance for downtime, and cost-sensitivity. Rather than concrete steps to cover every situation, we have general guidance for the process. diff --git a/docs/migrate/snapshot-migrate.md b/docs/migrate/snapshot-migrate.md new file mode 100644 index 00000000..0cf5f7be --- /dev/null +++ b/docs/migrate/snapshot-migrate.md @@ -0,0 +1,12 @@ +--- +layout: default +title: Snapshot migration +parent: Migrate to OpenSearch +nav_order: 5 +--- + +# Snapshot migration + +One popular approach is to take a [snapshot](../../opensearch/snapshot-restore/) of your Elasticsearch OSS 6.x or 7.x indices, [create an OpenSearch cluster](../../opensearch/install/), restore the snapshot on the new cluster, and point your clients to the new host. + +The snapshot approach can mean running two clusters in parallel, but lets you validate that the OpenSearch cluster is working in a way that meets your needs prior to modifying the Elasticsearch OSS cluster. diff --git a/docs/migrate/upgrade-migrate.md b/docs/migrate/upgrade-migrate.md new file mode 100644 index 00000000..13e25db2 --- /dev/null +++ b/docs/migrate/upgrade-migrate.md @@ -0,0 +1,176 @@ +--- +layout: default +title: Upgrade migration +parent: Migrate to OpenSearch +nav_order: 15 +--- + +# Upgrade approach (Linux) + +If you want to upgrade your existing Elasticsearch OSS cluster to OpenSearch and find the [snapshot approach](../snapshot-migrate/) unappealing, you must first upgrade your Elasticsearch OSS cluster to version 6.x or 7.x. + +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 (e.g. 6.5 to 6.8) and also support a single path to the next major version (e.g. 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 (e.g. 6.5 to 6.8) and the next major version (for example, 6.x to 7.10.2). Cluster restart upgrades are simpler to perform, but require downtime. + +To safeguard against data loss, we recommend that you take a [snapshot](../../opensearch/snapshot-restore/) of all indices prior to any upgrade. +{: .tip } + + +## Upgrade 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 indices, upgrade to 7.10.2, and upgrade to OpenSearch. | Upgrade to 6.8, reindex all 5.x indices, and upgrade to OpenSearch. +6.x | Upgrade to 6.8, upgrade to 7.10.2, and upgrade to OpenSearch. | Upgrade to OpenSearch. +7.x | Upgrade to OpenSearch. | Upgrade to OpenSearch. + + +## Upgrade Elasticsearch OSS + +1. Disable shard allocation to prevent Elasticsearch OSS from replicating shards as you shut down nodes: + + ```json + PUT _cluster/settings + { + "persistent": { + "cluster.routing.allocation.enable": "primaries" + } + } + ``` + +1. Stop Elasticsearch OSS on one node (rolling upgrade) or all nodes (cluster restart upgrade). + + On Linux distributions that use systemd, use this command: + + ```bash + sudo systemctl stop elasticsearch.service + ``` + + For tarball installations, find the process ID (`ps aux`) and kill it (`kill `). + +1. Upgrade the node (rolling) or all nodes (cluster restart). + + The exact command varies by package manager, but likely looks something like this: + + ```bash + 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`, and `logs` directories. Ideally, these directories should have their own, independent paths and *not* be colocated with the Elasticsearch application directory. Then set the `ES_PATH_CONF` environment variable to the directory that contains `elasticsearch.yml` (e.g. `/etc/elasticesarch/`). In `elasticsearch.yml`, set `path.data` and `path.logs` to your `data` and `logs` directories (e.g. `/var/lib/elasticsearch` and `/var/log/opensearch`). + +1. Restart Elasticsearch OSS on the node (rolling) or all nodes (cluster restart). + + On Linux distributions that use systemd, use this command: + + ```bash + sudo systemctl start elasticsearch.service + ``` + + For tarball installations, run `./bin/elasticsearch -d`. + +1. 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: + + ```bash + # Elasticsearch OSS + curl -XGET 'localhost:9200/_nodes/_all?pretty=true' + # Open Distro for Elasticsearch + curl -XGET 'https://localhost:9200/_nodes/_all?pretty=true' -u 'admin:admin' -k + ``` + + Specifically, check the `nodes.node-id.version` portion of the response. + +1. (Rolling) Repeat steps 2--5 until all nodes are using the new version. + +1. After all nodes are using the new version, re-enable shard allocation: + + ```json + PUT _cluster/settings + { + "persistent": { + "cluster.routing.allocation.enable": "all" + } + } + ``` + +1. If you upgraded from 5.x to 6.x, [reindex](../../opensearch/reindex-data/) all indices. + +1. Repeat all steps as necessary until you arrive at your desired Elasticsearch OSS version. + + +## Upgrade to OpenSearch + +1. Disable shard allocation to prevent Elasticsearch OSS from replicating shards as you shut down nodes: + + ```json + PUT _cluster/settings + { + "persistent": { + "cluster.routing.allocation.enable": "primaries" + } + } + ``` + +1. Stop Elasticsearch OSS on one node (rolling upgrade) or all nodes (cluster restart upgrade). + + On Linux distributions that use systemd, use this command: + + ```bash + sudo systemctl stop elasticsearch.service + ``` + + For tarball installations, find the process ID and kill it. + +1. Upgrade the node (rolling) or all nodes (cluster restart). + + 1. Extract the OpenSearch tarball to a new directory to ensure you **do not overwrite** your Elasticsearch OSS `config`, `data`, and `logs` directories. + + 1. (Optional) Copy or move your Elasticsearch OSS `data` and `logs` directories to new paths. For example, you might move `/var/lib/elasticsearch` to `/var/lib/opensearch`. + + 1. Set the `OPENSEARCH_PATH_CONF` environment variable to the directory that contains `opensearch.yml` (e.g. `/etc/opensearch`). + + 1. In `opensearch.yml`, set `path.data` and `path.logs`. If you are migrating from Elasticsearch OSS, you might also want to disable the security plugin for the time being. `opensearch.yml` might look something like this: + + ```yml + path.data: /var/lib/opensearch + path.logs: /var/log/opensearch + plugins.security.disabled: true + ``` + + 1. Port your settings from `elasticsearch.yml` to `opensearch.yml`. Most settings use the same names. At a minimum, specify `cluster.name`, `node.name`, `discovery.seed_hosts`, and `cluster.initial_master_nodes`. + + 1. (Optional) Add your certificates to your `config` directory, add them to `opensearch.yml`, and initialize the security plugin. + +1. Start OpenSearch on the node (rolling) or all nodes (cluster restart). + + For the tarball, run `./bin/opensearch -d`. + +1. 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: + + ```bash + # Security plugin disabled + curl -XGET 'localhost:9200/_nodes/_all?pretty=true' + # 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. + +1. (Rolling) Repeat steps 2--5 until all nodes are using OpenSearch. + +1. After all nodes are using the new version, re-enable shard allocation: + + ```json + PUT _cluster/settings + { + "persistent": { + "cluster.routing.allocation.enable": "all" + } + } + ```