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

Added upgrade tool docs

_upgrade-to/upgrade-to.md

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