From 0686ae05b57bd6409289cba469eae58f42e2343f Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 1 Oct 2021 01:21:16 -0700 Subject: [PATCH 1/4] 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. From dda5e2a53526df8869de69f42f8e71cf85f5399d Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 1 Oct 2021 11:26:24 -0700 Subject: [PATCH 2/4] fixed indendation feedback --- _upgrade-to/upgrade-to.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_upgrade-to/upgrade-to.md b/_upgrade-to/upgrade-to.md index e852fa1c..0d554370 100644 --- a/_upgrade-to/upgrade-to.md +++ b/_upgrade-to/upgrade-to.md @@ -227,12 +227,12 @@ Check [Upgrade paths]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/#upgrad 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 } + Make sure you run this tool as the same user running the current Elasticsearch service. + {: .note } - ```json - ./bin/opensearch-upgrade - ``` + ```json + ./bin/opensearch-upgrade + ``` 1. Stop Elasticsearch OSS on the node. From c2f1018b3685c6ce7f41135f8b237cd08fa0ffe4 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Sun, 3 Oct 2021 10:50:46 -0700 Subject: [PATCH 3/4] incorporated feedback --- _upgrade-to/upgrade-to.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/_upgrade-to/upgrade-to.md b/_upgrade-to/upgrade-to.md index 0d554370..cd403f7e 100644 --- a/_upgrade-to/upgrade-to.md +++ b/_upgrade-to/upgrade-to.md @@ -221,18 +221,37 @@ Check [Upgrade paths]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/#upgrad 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 } + Make sure you run this tool as the same user running the current Elasticsearch service. + {: .note } - ```json - ./bin/opensearch-upgrade - ``` + ```json + ./bin/opensearch-upgrade + ``` 1. Stop Elasticsearch OSS on the node. @@ -270,6 +289,6 @@ Behind the scenes, the `opensearch-upgrade` tool performs the following tasks in 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. 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. From 370ff0fc57475e4cd255039efffef90f8afbf2c4 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Sun, 3 Oct 2021 10:57:58 -0700 Subject: [PATCH 4/4] spacing --- _upgrade-to/upgrade-to.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/_upgrade-to/upgrade-to.md b/_upgrade-to/upgrade-to.md index cd403f7e..b21ec89c 100644 --- a/_upgrade-to/upgrade-to.md +++ b/_upgrade-to/upgrade-to.md @@ -265,22 +265,22 @@ Check [Upgrade paths]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/#upgrad 1. Start OpenSearch on the node: - ```json - ./bin/opensearch -d. - ``` + ```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" - } + ```json + PUT _cluster/settings + { + "persistent": { + "cluster.routing.allocation.enable": "all" } - ``` + } + ``` ### How it works