Initial migration content

This commit is contained in:
aetter 2021-06-03 16:17:17 -07:00
parent 9a3ec29dd8
commit 9f34374691
4 changed files with 213 additions and 0 deletions

View File

@ -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.

11
docs/migrate/index.md Normal file
View File

@ -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.

View File

@ -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.

View File

@ -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 <pid>`).
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"
}
}
```