Merge pull request #193 from opensearch-project/upgrade-cli

Added upgrade tool docs
This commit is contained in:
Andrew Etter 2021-10-05 15:21:14 -07:00 committed by GitHub
commit 8ca1b7d932
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 113 additions and 0 deletions

View File

@ -179,3 +179,116 @@ If you are upgrading an Open Distro for Elasticsearch cluster, we recommend firs
} }
} }
``` ```
## Upgrade tool
The `opensearch-upgrade` tool lets you automate some of the steps in [Upgrade to OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/#upgrade-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]({{site.url}}{{site.baseurl}}/opensearch/install/tar/) distribution:
Check [Upgrade paths]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/#upgrade-paths) to make sure that the version youre upgrading to is supported and whether you need to upgrade to a supported Elasticsearch OSS version first.
{: .note }
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. On any one of the nodes, download and extract the OpenSearch tarball to a new directory.
1. Make sure the following environment variables are set:
- `ES_HOME` - Path to the existing Elasticsearch installation home.
```bash
export ES_HOME = /home/workspace/upgrade-demo/node1/elasticsearch-7.10.2
```
- `ES_PATH_CONF` - Path to the existing Elasticsearch config directory.
```bash
export ES_PATH_CONF = /home/workspace/upgrade-demo/node1/os-config
```
- `OPENSEARCH_HOME` - Path to the OpenSearch installation home.
```bash
export OPENSEARCH_HOME = /home/workspace/upgrade-demo/node1/opensearch-1.0.0
```
- `OPENSEARCH_PATH_CONF` - Path to the OpenSearch config directory.
```bash
export OPENSEARCH_PATH_CONF = /home/workspace/upgrade-demo/node1/opensearch-config
```
1. The `opensearch-upgrade` tool is in the `bin` 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.
{: .note }
```json
./bin/opensearch-upgrade
```
1. Stop Elasticsearch OSS on the node.
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. Start OpenSearch on the node:
```json
./bin/opensearch -d.
```
1. Repeat steps 2--6 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"
}
}
```
### How it works
Behind the scenes, the `opensearch-upgrade` tool performs the following tasks in sequence:
1. 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 the `ES_HOME` location.
1. 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.
1. Imports the settings from the `elasticsearch.yml` config file into the `opensearch.yml` config file.
1. 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.
1. Installs the core plugins that youve currently installed in the `$ES_HOME/plugins` directory. You must install all other third-party community plugins manually.
1. Imports the secure settings from the `elasticsearch.keystore` file (if any) into the `opensearch.keystore` file. If the keystore file is password protected, the `opensearch-upgrade` tool prompts you to enter the password.