From 0686ae05b57bd6409289cba469eae58f42e2343f Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 1 Oct 2021 01:21:16 -0700 Subject: [PATCH] Added upgrade tool docs --- _upgrade-to/upgrade-to.md | 94 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) diff --git a/_upgrade-to/upgrade-to.md b/_upgrade-to/upgrade-to.md index a415b621..e852fa1c 100644 --- a/_upgrade-to/upgrade-to.md +++ b/_upgrade-to/upgrade-to.md @@ -179,3 +179,97 @@ 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 you’re 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. + - `ES_PATH_CONF` - Path to the existing Elasticsearch config directory. + - `OPENSEARCH_HOME` - Path to the OpenSearch installation home. + - `OPENSEARCH_PATH_CONF` - Path to the OpenSearch config directory. + +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 `). + +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 you’ve 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.