From 9e42f54d1b68bc778458e488dba8e7506087ee25 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 1 Feb 2023 10:28:53 -0800 Subject: [PATCH 01/54] Migrating to new branch since the ToC structure has changed so much Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/migrate-from-es.md | 211 ++++++++++++++++++ .../upgrade-opensearch/upgrade-overview.md | 95 ++++++++ 2 files changed, 306 insertions(+) create mode 100644 _install-and-configure/upgrade-opensearch/migrate-from-es.md create mode 100644 _install-and-configure/upgrade-opensearch/upgrade-overview.md diff --git a/_install-and-configure/upgrade-opensearch/migrate-from-es.md b/_install-and-configure/upgrade-opensearch/migrate-from-es.md new file mode 100644 index 0000000000..da548e1dc6 --- /dev/null +++ b/_install-and-configure/upgrade-opensearch/migrate-from-es.md @@ -0,0 +1,211 @@ +--- +layout: default +title: Upgrade OpenSearch - Docker +parent: Install OpenSearch +nav_order: 1000 +--- + +# Upgrade OpenSearch - Docker + +This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. +{:.note} + +## Prepare to upgrade + +Review the [Upgrade Overview](NEEDLINK) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. + +OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. +{: .note} + +### Rolling upgrade + +1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. +```bash +curl -X POST "http://localhost:9200/_flush?pretty" +``` +**Sample response:** +```bash +{ + "_shards" : { + "total" : 4, + "successful" : 4, + "failed" : 0 + } +} +``` +1. Disable shard replication to prevent shard replicas from being created while nodes are being taken offline. +```bash +curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' +``` +**Sample response:** +```bash +{ + "acknowledged" : true, + "persistent" : { + "cluster" : { + "routing" : { + "allocation" : { + "enable" : "primaries" + } + } + } + }, + "transient" : { } +} +``` +1. Verify the health of your OpenSearch cluster. +```bash +curl "http://localhost:9200/_cluster/health?pretty" +``` +A status of **green** indicates that all primary and replica shards are allocated. +**Sample response:** +```bash +{ + "cluster_name" : "opensearch-dev-cluster", + "status" : "green", + "timed_out" : false, + "number_of_nodes" : 4, + "number_of_data_nodes" : 4, + "discovered_master" : true, + "active_primary_shards" : 2, + "active_shards" : 4, + "relocating_shards" : 0, + "initializing_shards" : 0, + "unassigned_shards" : 0, + "delayed_unassigned_shards" : 0, + "number_of_pending_tasks" : 0, + "number_of_in_flight_fetch" : 0, + "task_max_waiting_in_queue_millis" : 0, + "active_shards_percent_as_number" : 100.0 +} +``` +1. List the running containers in your OpenSearch cluster and make a note of the container IDs and names. +```bash +docker container ls +``` +**Sample output:** +```bash +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +af1ec1c3fef7 opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-04 +1d47c0da60ad opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-03 +f553b5ec870b opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-02 +934e4325d9a4 opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-01 +``` +1. Query `_cat/nodes` to determine which node is operating as the cluster manager. Note that OpenSearch 1.x versions use the heading "master," which has been deprecated and replaced by "cluster_manager" in OpenSearch 2.x versions. +```bash +curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t +``` +**Sample output:** +```bash +name version node.role master +os-node-03 1.3.7 dimr - +os-node-04 1.3.7 dimr - +os-node-01 1.3.7 dimr - +os-node-02 1.3.7 dimr * +``` +1. Select a node to upgrade first. Cluster manager-eligible nodes should be upgraded last because nodes cannot join an OpenSearch cluster if they are running an older version of OpenSearch than the elected cluster manager. +```bash +docker stop && docker container rm +``` +**Sample output:** +```bash +$ docker stop 934e4325d9a4 && docker rm 934e4325d9a4 +934e4325d9a4 +934e4325d9a4 +``` +**Important:** Do not delete the volume associated with the container when you delete the container. The new OpenSearch container will use the existing volume. Deleting the volume will result in data loss. +1. Confirm that the associated node has been dismissed from the cluster. +```bash +curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t +``` +**Sample output:** +```bash +name version node.role master +os-node-03 1.3.7 dimr - +os-node-04 1.3.7 dimr - +os-node-02 1.3.7 dimr * +``` +`os-node-01` is no longer listed because the container has been stopped and deleted. +1. Deploy a new container running the desired version of OpenSearch, mapped to the same volume as the container you deleted. +```bash +docker run -d \ + -p 9200:9200 -p 9600:9600 \ + -e "discovery.seed_hosts=os-node-01,os-node-02,os-node-03,os-node-04" -e "DISABLE_SECURITY_PLUGIN=true" \ + -e "DISABLE_INSTALL_DEMO_CONFIG=true" -e "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" \ + -e "cluster.name=opensearch-dev-cluster" -e "node.name=os-node-01" \ + -e "cluster.initial_cluster_manager_nodes=os-node-01,os-node-02,os-node-03,os-node-04" \ + -e "bootstrap.memory_lock=true" -e "path.repo=/mnt/snapshots" \ + --ulimit nofile=65536:65536 --ulimit memlock=-1:-1 \ + -v os-data-01:/usr/share/opensearch/data \ + -v /Users/username/Documents/opensearch/snapshots/repo-01:/mnt/snapshots \ + --network opensearch-dev-net \ + --name os-node-01 \ + opensearchproject/opensearch:2.4.1 +``` +**Sample output:** +```bash +778e33168157e39814cb66ff81523c9d40772d122472c718bb3839e0c365cfe2 +``` +1. Give the new container time to start, then query `_cat/nodes` to confirm that the new node has joined the cluster, and that it is running the desired version of OpenSearch. +```bash +curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t +``` +**Sample output:** +```bash +name version node.role master +os-node-03 1.3.7 dimr - +os-node-04 1.3.7 dimr - +os-node-02 1.3.7 dimr * +os-node-01 2.4.1 dimr - +``` +1. Repeat steps 5 through 9 for each node in your cluster. Remember to upgrade an eligible cluster manager node last. When you are finished replacing the last node, query `_cat/nodes` to confirm that all nodes have joined the cluster and are running the desired version of OpenSearch. +```bash +curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t +``` +**Sample output:** +```bash +name version node.role master +os-node-02 2.4.1 dimr - +os-node-03 2.4.1 dimr * +os-node-04 2.4.1 dimr - +os-node-01 2.4.1 dimr - +``` +There are no longer any cluster manager-eligible nodes running the old version, so a cluster manager running the new version is elected. The cluster has now been bootstrapped with the new version. +1. Reenable shard replication. +```bash +curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":null}}' +``` +**Sample output:** +```bash +{ + "acknowledged" : true, + "persistent" : { }, + "transient" : { } +} +``` +1. Confirm that the cluster is healthy. +```bash +curl "http://localhost:9200/_cluster/health?pretty" +``` +**Sample output:** +```bash +{ + "cluster_name" : "opensearch-dev-cluster", + "status" : "green", + "timed_out" : false, + "number_of_nodes" : 4, + "number_of_data_nodes" : 4, + "discovered_master" : true, + "discovered_cluster_manager" : true, + "active_primary_shards" : 2, + "active_shards" : 4, + "relocating_shards" : 0, + "initializing_shards" : 0, + "unassigned_shards" : 0, + "delayed_unassigned_shards" : 0, + "number_of_pending_tasks" : 0, + "number_of_in_flight_fetch" : 0, + "task_max_waiting_in_queue_millis" : 0, + "active_shards_percent_as_number" : 100.0 +} +```version- \ No newline at end of file diff --git a/_install-and-configure/upgrade-opensearch/upgrade-overview.md b/_install-and-configure/upgrade-opensearch/upgrade-overview.md new file mode 100644 index 0000000000..e8d8901774 --- /dev/null +++ b/_install-and-configure/upgrade-opensearch/upgrade-overview.md @@ -0,0 +1,95 @@ +--- +layout: default +title: Upgrade Overview +parent: Install OpenSearch +nav_order: 999 +--- + +# Upgrade Overview + +The OpenSearch Project releases regular updates that include new features, enhancements, and bug fixes. OpenSearch uses [Semantic Versioning](https://semver.org/), which means that breaking changes are only introduced between major version releases. To learn about upcoming features and fixes, review the [OpenSearch Project Roadmap](https://github.com/orgs/opensearch-project/projects/1) on GitHub. To see a list of previous releases, or to learn more about how OpenSearch uses versioning, check out the [Release Schedule and Maintenance Policy]({{site.url}}/releases.html). + +OpenSearch nodes and indexes are backwards-compatible by one major version. That means, for example, that you can restore an index to an OpenSearch 2.4.1 cluster from a snapshot that was taken on an OpenSearch 1.x cluster. Index compatibility is determined by the version of OpenSearch or Lucene that created the index. If an index was created by an OpenSearch cluster running version 1.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. + +The following table can be used as a reference for Lucene versions running in OpenSearch 1.0 and later and [ElasticSearch](https://www.elastic.co/) 6.8 and later. + +Lucene Version | OpenSearch Version | ElasticSearch Version +:--------: | :--------: | :--------: +9.4.2 | 2.5.0
2.4.1 | 8.6 +9.4.1 | 2.4.0 | - +9.4.0 | - | 8.5 +9.3.0 | 2.3.0
2.2.x | 8.4 +9.2.0 | 2.1.0 | 8.3 +9.1.0 | 2.0.x | 8.2 +9.0.0 | - | 8.1
8.0 +8.11.1 | - | 7.17 +8.10.1 | 1.3.x
1.2.x | 7.16 +8.9.0 | 1.1.0 | 7.15
7.14 +8.8.2 | 1.0.0 | 7.13 +8.8.0 | - | 7.12 +8.7.0 | - | 7.11
7.10 +8.6.2 | - | 7.9 +8.5.1 | - | 7.8
7.7 +8.4.0 | - | 7.6 +8.3.0 | - | 7.5 +8.2.0 | - | 7.4 +8.1.0 | - | 7.3 +8.0.0 | - | 7.2
7.1 +7.7.3 | - | 6.8 + +If your upgrade path spans more than a single major version, and you want to maintain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. + +## Workflow considerations + +You should take time to plan the process before making any changes to your cluster. For example, consider how long the upgrade process will take. If your cluster is being used in production, how impactful is downtime? Do you have infrastructure in place to stand up the new cluster in a dev environment before you move it into production, or do you need to upgrade the hosts in-place? The answers to questions like these will help you determine which upgrade path will work best in your environment. At a minimum, you should: + +- [Review breaking changes](#review-breaking-changes) +- [Review the OpenSearch tools compatibility matrices](#review-the-opensearch-tools-compatibility-matrices) +- [Check plugin compatibility](#check-plugin-compatibility) +- [Back up configuration files](#back-up-configuration-files) +- [Create a snapshot](#create-a-snapshot) + +Before upgrading your production cluster, test the new version of OpenSearch in a development environment to validate functionality and compatibility with components in your production workflow. +{: .tip} + +Stop any non-essential indexing before you begin the upgrade procedure. +{: .tip} + +### Review breaking changes + +It's important to determine how the new version of OpenSearch will fit into your production environment. Review the list of [breaking changes]({{site.url}}{{site.baseurl}}/breaking-changes/) before beginning any upgrade procedures to determine if you will need to make adjustments in your workflow. For example, upstream or downstream components might need to be adjusted to take an API change into account. + +### Review the OpenSearch tools compatibility matrices + +Your OpenSearch cluster may interact with other services in your environment, like Logstash or Beats. Check the [OpenSearch tools compatibility matrices]({{site.url}}{{site.baseurl}}/tools/index/#compatibility-matrices) to see if any of your tools will also need to be upgraded. + +### Check plugin compatibility + +Review the plugins you use to determine whether or not they are compatible with the target version of OpenSearch. Many of the official plugins can be found in the official [OpenSearch Project](https://github.com/opensearch-project) repository on GitHub. If you use any unofficial or third party plugins, then you should check the documentation for those plugins to determine if they will be compatible. + +### Back up configuration files + +Mitigate the risk of data loss by backing up any important files before you start an upgrade. Generally speaking, these files will be located in `opensearch/config` (OpenSearch) and `opensearch-dashboards/config` (OpenSearch Dashboards). Some examples include `opensearch.yml`, `opensearch_dashboards.yml`, security plugin backups, and TLS certificates. Once you identify which files you need to back up, copy them to remote storage so they can be restored, if necessary. + +### Create a snapshot + +We recommend that you back up your cluster state and indexes using [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/). If the security plugin is enabled then you will need to take a additional steps, because the `.opendistro_security` index can't be directly restored. See [A word of caution]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/#a-word-of-caution) for details about backing up and restoring your security settings. + +## Upgrade methods + +Choose an appropriate method for upgrading your cluster to a new version of OpenSearch based on your requirements. + +- [Rolling upgrade](#rolling-upgrade) allows you to upgrade nodes individually without stopping the cluster. +- [Cluster restart upgrade](#cluster-restart-upgrade) allows the upgrade to be performed while the cluster is stopped. + +Upgrades spanning more than a single major version of OpenSearch will require additional effort due to the need for reindexing. You should upgrade in steps, one major version at a time. After each upgrade you should reindex because OpenSearch is not compatible with indexes that are more than a single major version behind your cluster's OpenSearch/Lucene version. For more information, refer to the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API. + +### Rolling upgrade + +Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Shard replication is stopped temporarily, then nodes are upgraded one at a time. A variation of the rolling upgrade, often referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. + +OpenSearch nodes cannot join a cluster if the cluster manager is running a newer version of OpenSearch than the node requesting membership. To avoid this issue, you upgrade cluster manager-eligible nodes last. + +### Cluster restart upgrade + +OpenSearch administrators might choose a restart upgrade if they aren't comfortable performing maintenance on a running cluster, if the cluster is being migrated to different infrastructure, or if they manage their cluster with [Docker Compose](https://github.com/docker/compose). During a rolling upgrade, only a single node is offline at any point in time. The cluster restart upgrade, however, involves stopping all nodes in the cluster, performing the upgrade, and starting the cluster back up. \ No newline at end of file From 11ec719e5bca72824d0aac2157e593bc2f027993 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 1 Feb 2023 13:17:28 -0800 Subject: [PATCH 02/54] Making changes Signed-off-by: JeffH-AWS --- .../{upgrade-overview.md => index.md} | 3 +-- .../upgrade-opensearch/migrate-from-es.md | 10 +++++----- 2 files changed, 6 insertions(+), 7 deletions(-) rename _install-and-configure/upgrade-opensearch/{upgrade-overview.md => index.md} (99%) diff --git a/_install-and-configure/upgrade-opensearch/upgrade-overview.md b/_install-and-configure/upgrade-opensearch/index.md similarity index 99% rename from _install-and-configure/upgrade-opensearch/upgrade-overview.md rename to _install-and-configure/upgrade-opensearch/index.md index e8d8901774..9109ff3637 100644 --- a/_install-and-configure/upgrade-opensearch/upgrade-overview.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -1,8 +1,7 @@ --- layout: default title: Upgrade Overview -parent: Install OpenSearch -nav_order: 999 +nav_order: 1 --- # Upgrade Overview diff --git a/_install-and-configure/upgrade-opensearch/migrate-from-es.md b/_install-and-configure/upgrade-opensearch/migrate-from-es.md index da548e1dc6..0325754769 100644 --- a/_install-and-configure/upgrade-opensearch/migrate-from-es.md +++ b/_install-and-configure/upgrade-opensearch/migrate-from-es.md @@ -1,18 +1,18 @@ --- layout: default -title: Upgrade OpenSearch - Docker -parent: Install OpenSearch -nav_order: 1000 +title: Upgrading OpenSearch +parent: Upgrade Overview +nav_order: 10 --- -# Upgrade OpenSearch - Docker +# OpenSearch Version Upgrades This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. {:.note} ## Prepare to upgrade -Review the [Upgrade Overview](NEEDLINK) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. +Before you upgrade, review [Upgrade Overview](NEEDLINK) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. {: .note} From 24489b0cb89f5e71557189fee82e93e71c6363c3 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 1 Feb 2023 13:19:50 -0800 Subject: [PATCH 03/54] Added caveat to upgrade spans Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 9109ff3637..623c67e902 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -36,7 +36,7 @@ Lucene Version | OpenSearch Version | ElasticSearch Version 8.0.0 | - | 7.2
7.1 7.7.3 | - | 6.8 -If your upgrade path spans more than a single major version, and you want to maintain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. +If your upgrade path spans more than a single major version, and you want to maintain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearc before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. ## Workflow considerations From 5fed608c4646425d89d1e9af69929c326a2601b7 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 1 Feb 2023 13:34:32 -0800 Subject: [PATCH 04/54] Add blurb about the context of the guide - will revisit and add later just getting bones together Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/migrate-from-es.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/_install-and-configure/upgrade-opensearch/migrate-from-es.md b/_install-and-configure/upgrade-opensearch/migrate-from-es.md index 0325754769..3f5502b082 100644 --- a/_install-and-configure/upgrade-opensearch/migrate-from-es.md +++ b/_install-and-configure/upgrade-opensearch/migrate-from-es.md @@ -12,11 +12,15 @@ This guide assumes that you are comfortable working from the Linux command line ## Prepare to upgrade -Before you upgrade, review [Upgrade Overview](NEEDLINK) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. +Before you upgrade, review [Upgrade Overview]({{site.url}}{{site.baseurl}}/upgrade-opensearch/index/) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. {: .note} +## About this guide + +Sample output and API responses included in this document were generated in a development environment using Docker. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. + ### Rolling upgrade 1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. From ee1d827a1967ce737a0b7e244e925ec34f4963e6 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 1 Feb 2023 13:45:18 -0800 Subject: [PATCH 05/54] Reordering sections Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/migrate-from-es.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/migrate-from-es.md b/_install-and-configure/upgrade-opensearch/migrate-from-es.md index 3f5502b082..30da901b14 100644 --- a/_install-and-configure/upgrade-opensearch/migrate-from-es.md +++ b/_install-and-configure/upgrade-opensearch/migrate-from-es.md @@ -10,17 +10,17 @@ nav_order: 10 This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. {:.note} -## Prepare to upgrade +### About this guide + +Sample output and API responses included in this document were generated in a development environment. Testing was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. + +### Prepare to upgrade Before you upgrade, review [Upgrade Overview]({{site.url}}{{site.baseurl}}/upgrade-opensearch/index/) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. {: .note} -## About this guide - -Sample output and API responses included in this document were generated in a development environment using Docker. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. - ### Rolling upgrade 1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. From d6d1277b55895e95bd10ed9f30c5b35b0b9a0b2b Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Fri, 3 Feb 2023 09:39:49 -0800 Subject: [PATCH 06/54] Adding redirects but I think I'm going to rename the pages Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 6 ++++-- .../upgrade-opensearch/migrate-from-es.md | 2 ++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 623c67e902..bd5b631beb 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -2,6 +2,8 @@ layout: default title: Upgrade Overview nav_order: 1 +redirect_from: + - /upgrade-opensearch/index/ --- # Upgrade Overview @@ -19,7 +21,7 @@ Lucene Version | OpenSearch Version | ElasticSearch Version 9.4.0 | - | 8.5 9.3.0 | 2.3.0
2.2.x | 8.4 9.2.0 | 2.1.0 | 8.3 -9.1.0 | 2.0.x | 8.2 +9.1.0 | 2.0.x | 8.2Oops 9.0.0 | - | 8.1
8.0 8.11.1 | - | 7.17 8.10.1 | 1.3.x
1.2.x | 7.16 @@ -36,7 +38,7 @@ Lucene Version | OpenSearch Version | ElasticSearch Version 8.0.0 | - | 7.2
7.1 7.7.3 | - | 6.8 -If your upgrade path spans more than a single major version, and you want to maintain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearc before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. +If your upgrade path spans more than a single major version, and you want to maintain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. ## Workflow considerations diff --git a/_install-and-configure/upgrade-opensearch/migrate-from-es.md b/_install-and-configure/upgrade-opensearch/migrate-from-es.md index 30da901b14..a50cfc825b 100644 --- a/_install-and-configure/upgrade-opensearch/migrate-from-es.md +++ b/_install-and-configure/upgrade-opensearch/migrate-from-es.md @@ -3,6 +3,8 @@ layout: default title: Upgrading OpenSearch parent: Upgrade Overview nav_order: 10 +redirect_from: + - /upgrade-opensearch/index/ --- # OpenSearch Version Upgrades From 1f2acf38d47251bb1f597362bd010a0126b9cfa5 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Fri, 3 Feb 2023 09:40:29 -0800 Subject: [PATCH 07/54] Renamed Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/migrate-from-es.md | 217 ------------------ 1 file changed, 217 deletions(-) delete mode 100644 _install-and-configure/upgrade-opensearch/migrate-from-es.md diff --git a/_install-and-configure/upgrade-opensearch/migrate-from-es.md b/_install-and-configure/upgrade-opensearch/migrate-from-es.md deleted file mode 100644 index a50cfc825b..0000000000 --- a/_install-and-configure/upgrade-opensearch/migrate-from-es.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -layout: default -title: Upgrading OpenSearch -parent: Upgrade Overview -nav_order: 10 -redirect_from: - - /upgrade-opensearch/index/ ---- - -# OpenSearch Version Upgrades - -This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. -{:.note} - -### About this guide - -Sample output and API responses included in this document were generated in a development environment. Testing was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. - -### Prepare to upgrade - -Before you upgrade, review [Upgrade Overview]({{site.url}}{{site.baseurl}}/upgrade-opensearch/index/) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. - -OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. -{: .note} - -### Rolling upgrade - -1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. -```bash -curl -X POST "http://localhost:9200/_flush?pretty" -``` -**Sample response:** -```bash -{ - "_shards" : { - "total" : 4, - "successful" : 4, - "failed" : 0 - } -} -``` -1. Disable shard replication to prevent shard replicas from being created while nodes are being taken offline. -```bash -curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' -``` -**Sample response:** -```bash -{ - "acknowledged" : true, - "persistent" : { - "cluster" : { - "routing" : { - "allocation" : { - "enable" : "primaries" - } - } - } - }, - "transient" : { } -} -``` -1. Verify the health of your OpenSearch cluster. -```bash -curl "http://localhost:9200/_cluster/health?pretty" -``` -A status of **green** indicates that all primary and replica shards are allocated. -**Sample response:** -```bash -{ - "cluster_name" : "opensearch-dev-cluster", - "status" : "green", - "timed_out" : false, - "number_of_nodes" : 4, - "number_of_data_nodes" : 4, - "discovered_master" : true, - "active_primary_shards" : 2, - "active_shards" : 4, - "relocating_shards" : 0, - "initializing_shards" : 0, - "unassigned_shards" : 0, - "delayed_unassigned_shards" : 0, - "number_of_pending_tasks" : 0, - "number_of_in_flight_fetch" : 0, - "task_max_waiting_in_queue_millis" : 0, - "active_shards_percent_as_number" : 100.0 -} -``` -1. List the running containers in your OpenSearch cluster and make a note of the container IDs and names. -```bash -docker container ls -``` -**Sample output:** -```bash -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -af1ec1c3fef7 opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-04 -1d47c0da60ad opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-03 -f553b5ec870b opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-02 -934e4325d9a4 opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-01 -``` -1. Query `_cat/nodes` to determine which node is operating as the cluster manager. Note that OpenSearch 1.x versions use the heading "master," which has been deprecated and replaced by "cluster_manager" in OpenSearch 2.x versions. -```bash -curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t -``` -**Sample output:** -```bash -name version node.role master -os-node-03 1.3.7 dimr - -os-node-04 1.3.7 dimr - -os-node-01 1.3.7 dimr - -os-node-02 1.3.7 dimr * -``` -1. Select a node to upgrade first. Cluster manager-eligible nodes should be upgraded last because nodes cannot join an OpenSearch cluster if they are running an older version of OpenSearch than the elected cluster manager. -```bash -docker stop && docker container rm -``` -**Sample output:** -```bash -$ docker stop 934e4325d9a4 && docker rm 934e4325d9a4 -934e4325d9a4 -934e4325d9a4 -``` -**Important:** Do not delete the volume associated with the container when you delete the container. The new OpenSearch container will use the existing volume. Deleting the volume will result in data loss. -1. Confirm that the associated node has been dismissed from the cluster. -```bash -curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t -``` -**Sample output:** -```bash -name version node.role master -os-node-03 1.3.7 dimr - -os-node-04 1.3.7 dimr - -os-node-02 1.3.7 dimr * -``` -`os-node-01` is no longer listed because the container has been stopped and deleted. -1. Deploy a new container running the desired version of OpenSearch, mapped to the same volume as the container you deleted. -```bash -docker run -d \ - -p 9200:9200 -p 9600:9600 \ - -e "discovery.seed_hosts=os-node-01,os-node-02,os-node-03,os-node-04" -e "DISABLE_SECURITY_PLUGIN=true" \ - -e "DISABLE_INSTALL_DEMO_CONFIG=true" -e "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" \ - -e "cluster.name=opensearch-dev-cluster" -e "node.name=os-node-01" \ - -e "cluster.initial_cluster_manager_nodes=os-node-01,os-node-02,os-node-03,os-node-04" \ - -e "bootstrap.memory_lock=true" -e "path.repo=/mnt/snapshots" \ - --ulimit nofile=65536:65536 --ulimit memlock=-1:-1 \ - -v os-data-01:/usr/share/opensearch/data \ - -v /Users/username/Documents/opensearch/snapshots/repo-01:/mnt/snapshots \ - --network opensearch-dev-net \ - --name os-node-01 \ - opensearchproject/opensearch:2.4.1 -``` -**Sample output:** -```bash -778e33168157e39814cb66ff81523c9d40772d122472c718bb3839e0c365cfe2 -``` -1. Give the new container time to start, then query `_cat/nodes` to confirm that the new node has joined the cluster, and that it is running the desired version of OpenSearch. -```bash -curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t -``` -**Sample output:** -```bash -name version node.role master -os-node-03 1.3.7 dimr - -os-node-04 1.3.7 dimr - -os-node-02 1.3.7 dimr * -os-node-01 2.4.1 dimr - -``` -1. Repeat steps 5 through 9 for each node in your cluster. Remember to upgrade an eligible cluster manager node last. When you are finished replacing the last node, query `_cat/nodes` to confirm that all nodes have joined the cluster and are running the desired version of OpenSearch. -```bash -curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t -``` -**Sample output:** -```bash -name version node.role master -os-node-02 2.4.1 dimr - -os-node-03 2.4.1 dimr * -os-node-04 2.4.1 dimr - -os-node-01 2.4.1 dimr - -``` -There are no longer any cluster manager-eligible nodes running the old version, so a cluster manager running the new version is elected. The cluster has now been bootstrapped with the new version. -1. Reenable shard replication. -```bash -curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":null}}' -``` -**Sample output:** -```bash -{ - "acknowledged" : true, - "persistent" : { }, - "transient" : { } -} -``` -1. Confirm that the cluster is healthy. -```bash -curl "http://localhost:9200/_cluster/health?pretty" -``` -**Sample output:** -```bash -{ - "cluster_name" : "opensearch-dev-cluster", - "status" : "green", - "timed_out" : false, - "number_of_nodes" : 4, - "number_of_data_nodes" : 4, - "discovered_master" : true, - "discovered_cluster_manager" : true, - "active_primary_shards" : 2, - "active_shards" : 4, - "relocating_shards" : 0, - "initializing_shards" : 0, - "unassigned_shards" : 0, - "delayed_unassigned_shards" : 0, - "number_of_pending_tasks" : 0, - "number_of_in_flight_fetch" : 0, - "task_max_waiting_in_queue_millis" : 0, - "active_shards_percent_as_number" : 100.0 -} -```version- \ No newline at end of file From 0bcba0070f99fc21366b7beaa270d83875379c5a Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Fri, 3 Feb 2023 09:40:39 -0800 Subject: [PATCH 08/54] Renamed Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/version-upgrade.md | 217 ++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 _install-and-configure/upgrade-opensearch/version-upgrade.md diff --git a/_install-and-configure/upgrade-opensearch/version-upgrade.md b/_install-and-configure/upgrade-opensearch/version-upgrade.md new file mode 100644 index 0000000000..a50cfc825b --- /dev/null +++ b/_install-and-configure/upgrade-opensearch/version-upgrade.md @@ -0,0 +1,217 @@ +--- +layout: default +title: Upgrading OpenSearch +parent: Upgrade Overview +nav_order: 10 +redirect_from: + - /upgrade-opensearch/index/ +--- + +# OpenSearch Version Upgrades + +This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. +{:.note} + +### About this guide + +Sample output and API responses included in this document were generated in a development environment. Testing was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. + +### Prepare to upgrade + +Before you upgrade, review [Upgrade Overview]({{site.url}}{{site.baseurl}}/upgrade-opensearch/index/) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. + +OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. +{: .note} + +### Rolling upgrade + +1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. +```bash +curl -X POST "http://localhost:9200/_flush?pretty" +``` +**Sample response:** +```bash +{ + "_shards" : { + "total" : 4, + "successful" : 4, + "failed" : 0 + } +} +``` +1. Disable shard replication to prevent shard replicas from being created while nodes are being taken offline. +```bash +curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' +``` +**Sample response:** +```bash +{ + "acknowledged" : true, + "persistent" : { + "cluster" : { + "routing" : { + "allocation" : { + "enable" : "primaries" + } + } + } + }, + "transient" : { } +} +``` +1. Verify the health of your OpenSearch cluster. +```bash +curl "http://localhost:9200/_cluster/health?pretty" +``` +A status of **green** indicates that all primary and replica shards are allocated. +**Sample response:** +```bash +{ + "cluster_name" : "opensearch-dev-cluster", + "status" : "green", + "timed_out" : false, + "number_of_nodes" : 4, + "number_of_data_nodes" : 4, + "discovered_master" : true, + "active_primary_shards" : 2, + "active_shards" : 4, + "relocating_shards" : 0, + "initializing_shards" : 0, + "unassigned_shards" : 0, + "delayed_unassigned_shards" : 0, + "number_of_pending_tasks" : 0, + "number_of_in_flight_fetch" : 0, + "task_max_waiting_in_queue_millis" : 0, + "active_shards_percent_as_number" : 100.0 +} +``` +1. List the running containers in your OpenSearch cluster and make a note of the container IDs and names. +```bash +docker container ls +``` +**Sample output:** +```bash +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +af1ec1c3fef7 opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-04 +1d47c0da60ad opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-03 +f553b5ec870b opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-02 +934e4325d9a4 opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-01 +``` +1. Query `_cat/nodes` to determine which node is operating as the cluster manager. Note that OpenSearch 1.x versions use the heading "master," which has been deprecated and replaced by "cluster_manager" in OpenSearch 2.x versions. +```bash +curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t +``` +**Sample output:** +```bash +name version node.role master +os-node-03 1.3.7 dimr - +os-node-04 1.3.7 dimr - +os-node-01 1.3.7 dimr - +os-node-02 1.3.7 dimr * +``` +1. Select a node to upgrade first. Cluster manager-eligible nodes should be upgraded last because nodes cannot join an OpenSearch cluster if they are running an older version of OpenSearch than the elected cluster manager. +```bash +docker stop && docker container rm +``` +**Sample output:** +```bash +$ docker stop 934e4325d9a4 && docker rm 934e4325d9a4 +934e4325d9a4 +934e4325d9a4 +``` +**Important:** Do not delete the volume associated with the container when you delete the container. The new OpenSearch container will use the existing volume. Deleting the volume will result in data loss. +1. Confirm that the associated node has been dismissed from the cluster. +```bash +curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t +``` +**Sample output:** +```bash +name version node.role master +os-node-03 1.3.7 dimr - +os-node-04 1.3.7 dimr - +os-node-02 1.3.7 dimr * +``` +`os-node-01` is no longer listed because the container has been stopped and deleted. +1. Deploy a new container running the desired version of OpenSearch, mapped to the same volume as the container you deleted. +```bash +docker run -d \ + -p 9200:9200 -p 9600:9600 \ + -e "discovery.seed_hosts=os-node-01,os-node-02,os-node-03,os-node-04" -e "DISABLE_SECURITY_PLUGIN=true" \ + -e "DISABLE_INSTALL_DEMO_CONFIG=true" -e "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" \ + -e "cluster.name=opensearch-dev-cluster" -e "node.name=os-node-01" \ + -e "cluster.initial_cluster_manager_nodes=os-node-01,os-node-02,os-node-03,os-node-04" \ + -e "bootstrap.memory_lock=true" -e "path.repo=/mnt/snapshots" \ + --ulimit nofile=65536:65536 --ulimit memlock=-1:-1 \ + -v os-data-01:/usr/share/opensearch/data \ + -v /Users/username/Documents/opensearch/snapshots/repo-01:/mnt/snapshots \ + --network opensearch-dev-net \ + --name os-node-01 \ + opensearchproject/opensearch:2.4.1 +``` +**Sample output:** +```bash +778e33168157e39814cb66ff81523c9d40772d122472c718bb3839e0c365cfe2 +``` +1. Give the new container time to start, then query `_cat/nodes` to confirm that the new node has joined the cluster, and that it is running the desired version of OpenSearch. +```bash +curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t +``` +**Sample output:** +```bash +name version node.role master +os-node-03 1.3.7 dimr - +os-node-04 1.3.7 dimr - +os-node-02 1.3.7 dimr * +os-node-01 2.4.1 dimr - +``` +1. Repeat steps 5 through 9 for each node in your cluster. Remember to upgrade an eligible cluster manager node last. When you are finished replacing the last node, query `_cat/nodes` to confirm that all nodes have joined the cluster and are running the desired version of OpenSearch. +```bash +curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t +``` +**Sample output:** +```bash +name version node.role master +os-node-02 2.4.1 dimr - +os-node-03 2.4.1 dimr * +os-node-04 2.4.1 dimr - +os-node-01 2.4.1 dimr - +``` +There are no longer any cluster manager-eligible nodes running the old version, so a cluster manager running the new version is elected. The cluster has now been bootstrapped with the new version. +1. Reenable shard replication. +```bash +curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":null}}' +``` +**Sample output:** +```bash +{ + "acknowledged" : true, + "persistent" : { }, + "transient" : { } +} +``` +1. Confirm that the cluster is healthy. +```bash +curl "http://localhost:9200/_cluster/health?pretty" +``` +**Sample output:** +```bash +{ + "cluster_name" : "opensearch-dev-cluster", + "status" : "green", + "timed_out" : false, + "number_of_nodes" : 4, + "number_of_data_nodes" : 4, + "discovered_master" : true, + "discovered_cluster_manager" : true, + "active_primary_shards" : 2, + "active_shards" : 4, + "relocating_shards" : 0, + "initializing_shards" : 0, + "unassigned_shards" : 0, + "delayed_unassigned_shards" : 0, + "number_of_pending_tasks" : 0, + "number_of_in_flight_fetch" : 0, + "task_max_waiting_in_queue_millis" : 0, + "active_shards_percent_as_number" : 100.0 +} +```version- \ No newline at end of file From f7959592a69c4db1d2b184b0f5c05e266dae19bd Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Fri, 3 Feb 2023 11:11:30 -0800 Subject: [PATCH 09/54] Changes Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/index.md | 138 +++++++++++++++--- .../upgrade-opensearch/version-upgrade.md | 3 +- 2 files changed, 116 insertions(+), 25 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index bd5b631beb..b844022a0a 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -14,29 +14,121 @@ OpenSearch nodes and indexes are backwards-compatible by one major version. That The following table can be used as a reference for Lucene versions running in OpenSearch 1.0 and later and [ElasticSearch](https://www.elastic.co/) 6.8 and later. -Lucene Version | OpenSearch Version | ElasticSearch Version -:--------: | :--------: | :--------: -9.4.2 | 2.5.0
2.4.1 | 8.6 -9.4.1 | 2.4.0 | - -9.4.0 | - | 8.5 -9.3.0 | 2.3.0
2.2.x | 8.4 -9.2.0 | 2.1.0 | 8.3 -9.1.0 | 2.0.x | 8.2Oops -9.0.0 | - | 8.1
8.0 -8.11.1 | - | 7.17 -8.10.1 | 1.3.x
1.2.x | 7.16 -8.9.0 | 1.1.0 | 7.15
7.14 -8.8.2 | 1.0.0 | 7.13 -8.8.0 | - | 7.12 -8.7.0 | - | 7.11
7.10 -8.6.2 | - | 7.9 -8.5.1 | - | 7.8
7.7 -8.4.0 | - | 7.6 -8.3.0 | - | 7.5 -8.2.0 | - | 7.4 -8.1.0 | - | 7.3 -8.0.0 | - | 7.2
7.1 -7.7.3 | - | 6.8 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Lucene VersionOpenSearch VersionElasticSearch Version
9.4.22.5.08.6
2.4.1
9.4.12.4.0-
9.4.0-8.5
9.3.02.3.0X2.2.x8.4
9.2.02.1.08.3
9.1.02.0.x8.2Oops
9.0.0-8.1X8.0
8.11.1-7.17
8.10.11.3.xX1.2.x7.16
8.9.01.1.07.15X7.14
8.8.21.0.07.13
8.8.0-7.12
8.7.0-7.11X7.10
8.6.2-7.9
8.5.1-7.8X7.7
8.4.0-7.6
8.3.0-7.5
8.2.0-7.4
8.1.0-7.3
8.0.0-7.2X7.1
7.7.3-6.8
If your upgrade path spans more than a single major version, and you want to maintain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. diff --git a/_install-and-configure/upgrade-opensearch/version-upgrade.md b/_install-and-configure/upgrade-opensearch/version-upgrade.md index a50cfc825b..2c1c2778d5 100644 --- a/_install-and-configure/upgrade-opensearch/version-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/version-upgrade.md @@ -1,10 +1,9 @@ --- layout: default title: Upgrading OpenSearch -parent: Upgrade Overview nav_order: 10 redirect_from: - - /upgrade-opensearch/index/ + - /upgrade-opensearch/version-upgrade/ --- # OpenSearch Version Upgrades From cb2c0bf7f6d11777d05f31813b5b1bc0a4181206 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Fri, 3 Feb 2023 11:12:58 -0800 Subject: [PATCH 10/54] Add note about Lucene table Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index b844022a0a..7883385e8d 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -14,6 +14,10 @@ OpenSearch nodes and indexes are backwards-compatible by one major version. That The following table can be used as a reference for Lucene versions running in OpenSearch 1.0 and later and [ElasticSearch](https://www.elastic.co/) 6.8 and later. +{% comment %} +The following table needs some love. There's an issue with the CSS (I think) that's not drawing a right border for tr:last-child +{% endcomment %} + From 3634fc89ba462377b97c0a3a8e2425c35d12dfc6 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Mon, 6 Feb 2023 09:26:44 -0800 Subject: [PATCH 11/54] Fixed table and identified some issues with overall site formatting - everything is left-justified site-wide Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/index.md | 164 ++++++++++-------- 1 file changed, 91 insertions(+), 73 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 7883385e8d..7e4fb9b8ef 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -18,6 +18,84 @@ The following table can be used as a reference for Lucene versions running in Op The following table needs some love. There's an issue with the CSS (I think) that's not drawing a right border for tr:last-child {% endcomment %} +If your upgrade path spans more than a single major version, and you want to maintain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. + +## Workflow considerations + +You should take time to plan the process before making any changes to your cluster. For example, consider how long the upgrade process will take. If your cluster is being used in production, how impactful is downtime? Do you have infrastructure in place to stand up the new cluster in a dev environment before you move it into production, or do you need to upgrade the hosts in-place? The answers to questions like these will help you determine which upgrade path will work best in your environment. At a minimum, you should: + +- [Review breaking changes](#review-breaking-changes) +- [Review the OpenSearch tools compatibility matrices](#review-the-opensearch-tools-compatibility-matrices) +- [Check plugin compatibility](#check-plugin-compatibility) +- [Back up configuration files](#back-up-configuration-files) +- [Create a snapshot](#create-a-snapshot) + +Before upgrading your production cluster, test the new version of OpenSearch in a development environment to validate functionality and compatibility with components in your production workflow. +{: .tip} + +Stop any non-essential indexing before you begin the upgrade procedure. +{: .tip} + +### Review breaking changes + +It's important to determine how the new version of OpenSearch will fit into your production environment. Review the list of [breaking changes]({{site.url}}{{site.baseurl}}/breaking-changes/) before beginning any upgrade procedures to determine if you will need to make adjustments in your workflow. For example, upstream or downstream components might need to be adjusted to take an API change into account. + +### Review the OpenSearch tools compatibility matrices + +Your OpenSearch cluster may interact with other services in your environment, like Logstash or Beats. Check the [OpenSearch tools compatibility matrices]({{site.url}}{{site.baseurl}}/tools/index/#compatibility-matrices) to see if any of your tools will also need to be upgraded. + +### Check plugin compatibility + +Review the plugins you use to determine whether or not they are compatible with the target version of OpenSearch. Many of the official plugins can be found in the official [OpenSearch Project](https://github.com/opensearch-project) repository on GitHub. If you use any unofficial or third party plugins, then you should check the documentation for those plugins to determine if they will be compatible. + +### Back up configuration files + +Mitigate the risk of data loss by backing up any important files before you start an upgrade. Generally speaking, these files will be located in `opensearch/config` (OpenSearch) and `opensearch-dashboards/config` (OpenSearch Dashboards). Some examples include `opensearch.yml`, `opensearch_dashboards.yml`, security plugin backups, and TLS certificates. Once you identify which files you need to back up, copy them to remote storage so they can be restored, if necessary. + +### Create a snapshot + +We recommend that you back up your cluster state and indexes using [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/). If the security plugin is enabled then you will need to take a additional steps, because the `.opendistro_security` index can't be directly restored. See [A word of caution]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/#a-word-of-caution) for details about backing up and restoring your security settings. + +## Upgrade methods + +Choose an appropriate method for upgrading your cluster to a new version of OpenSearch based on your requirements. + +- [Rolling upgrade](#rolling-upgrade) allows you to upgrade nodes individually without stopping the cluster. +- [Cluster restart upgrade](#cluster-restart-upgrade) allows the upgrade to be performed while the cluster is stopped. + +Upgrades spanning more than a single major version of OpenSearch will require additional effort due to the need for reindexing. You should upgrade in steps, one major version at a time. After each upgrade you should reindex because OpenSearch is not compatible with indexes that are more than a single major version behind your cluster's OpenSearch/Lucene version. For more information, refer to the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API. + +### Rolling upgrade + +Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Shard replication is stopped temporarily, then nodes are upgraded one at a time. A variation of the rolling upgrade, often referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. + +OpenSearch nodes cannot join a cluster if the cluster manager is running a newer version of OpenSearch than the node requesting membership. To avoid this issue, you upgrade cluster manager-eligible nodes last. + +### Cluster restart upgrade + +OpenSearch administrators might choose a restart upgrade if they aren't comfortable performing maintenance on a running cluster, if the cluster is being migrated to different infrastructure, or if they manage their cluster with [Docker Compose](https://github.com/docker/compose). During a rolling upgrade, only a single node is offline at any point in time. The cluster restart upgrade, however, involves stopping all nodes in the cluster, performing the upgrade, and starting the cluster back up. + +## Compatibility + +ADD TO ME! Here I'll add some commentary about what version compatibility considerations can be taken into account. Maybe another table or external link references would be good. + +### Lucene version reference + +If you plan to retain old indexes after the OpenSearch version upgrade, then you might need to reindex or reingest the data. Refer to the table below for Lucene versions across recent OpenSearch and Elasticsearch releases. + +
Lucene Version
@@ -25,12 +103,9 @@ The following table needs some love. There's an issue with the CSS (I think) tha - - - - - - + + + @@ -44,7 +119,7 @@ The following table needs some love. There's an issue with the CSS (I think) tha - + @@ -55,12 +130,12 @@ The following table needs some love. There's an issue with the CSS (I think) tha - + - + @@ -69,13 +144,13 @@ The following table needs some love. There's an issue with the CSS (I think) tha - + - + @@ -90,9 +165,9 @@ The following table needs some love. There's an issue with the CSS (I think) tha - + - + +
Lucene VersionElasticSearch Version
9.4.22.5.08.6
2.4.19.4.22.5.0
2.4.1		8.6
9.4.1
9.3.02.3.0X2.2.x2.3.0
2.2.x		 8.4
9.1.0 2.0.x8.2Oops8.2
9.0.0 -8.1X8.08.1
8.0
8.11.1
8.10.11.3.xX1.2.x1.3.x
1.2.x		 7.16
8.9.0 1.1.07.15X7.147.15
7.14
8.8.2
8.7.0 -7.11X7.107.11
7.10
\ No newline at end of file From 45c4889ebdf9f678c518d88003b7d856432a9c41 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Mon, 6 Feb 2023 10:38:46 -0800 Subject: [PATCH 12/54] Fixed table Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 7e4fb9b8ef..7085653f31 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -167,7 +167,8 @@ td { - 7.11
7.10 - + +End of the trimmed section --> \ No newline at end of file From 95bf43c58613a001e3f6ee91aa91a8dc5ee59837 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Tue, 7 Feb 2023 13:21:27 -0800 Subject: [PATCH 13/54] Fixing front matter Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 7085653f31..93bff32667 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -2,6 +2,7 @@ layout: default title: Upgrade Overview nav_order: 1 +has_children: true redirect_from: - /upgrade-opensearch/index/ --- @@ -100,7 +101,7 @@ td { Lucene Version OpenSearch Version - ElasticSearch Version + Elasticsearch Version 9.4.2 From 9bf43674bf5a72ddfdb9011f20a0daaca2fb5bcc Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Tue, 7 Feb 2023 13:29:35 -0800 Subject: [PATCH 14/54] Finally figured out how to make the ToC work - now the structure looks right Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/version-upgrade.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_install-and-configure/upgrade-opensearch/version-upgrade.md b/_install-and-configure/upgrade-opensearch/version-upgrade.md index 2c1c2778d5..9f99e09c4c 100644 --- a/_install-and-configure/upgrade-opensearch/version-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/version-upgrade.md @@ -1,6 +1,7 @@ --- layout: default title: Upgrading OpenSearch +parent: Upgrade Overview nav_order: 10 redirect_from: - /upgrade-opensearch/version-upgrade/ From 46b1cc03cf00b88ad55afe5d144cfeb1c8e602fb Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Tue, 7 Feb 2023 13:40:46 -0800 Subject: [PATCH 15/54] Fix nav order on index, rename pages for consistency with ToC gerund usage, and fixed capitalization of elasticsearch Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 6 +++--- .../upgrade-opensearch/version-upgrade.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 93bff32667..3e59c25ffc 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -1,19 +1,19 @@ --- layout: default -title: Upgrade Overview +title: Upgrading OpenSearch nav_order: 1 has_children: true redirect_from: - /upgrade-opensearch/index/ --- -# Upgrade Overview +# Upgrade OpenSearch The OpenSearch Project releases regular updates that include new features, enhancements, and bug fixes. OpenSearch uses [Semantic Versioning](https://semver.org/), which means that breaking changes are only introduced between major version releases. To learn about upcoming features and fixes, review the [OpenSearch Project Roadmap](https://github.com/orgs/opensearch-project/projects/1) on GitHub. To see a list of previous releases, or to learn more about how OpenSearch uses versioning, check out the [Release Schedule and Maintenance Policy]({{site.url}}/releases.html). OpenSearch nodes and indexes are backwards-compatible by one major version. That means, for example, that you can restore an index to an OpenSearch 2.4.1 cluster from a snapshot that was taken on an OpenSearch 1.x cluster. Index compatibility is determined by the version of OpenSearch or Lucene that created the index. If an index was created by an OpenSearch cluster running version 1.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. -The following table can be used as a reference for Lucene versions running in OpenSearch 1.0 and later and [ElasticSearch](https://www.elastic.co/) 6.8 and later. +The following table can be used as a reference for Lucene versions running in OpenSearch 1.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. {% comment %} The following table needs some love. There's an issue with the CSS (I think) that's not drawing a right border for tr:last-child diff --git a/_install-and-configure/upgrade-opensearch/version-upgrade.md b/_install-and-configure/upgrade-opensearch/version-upgrade.md index 9f99e09c4c..81e4eadfdc 100644 --- a/_install-and-configure/upgrade-opensearch/version-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/version-upgrade.md @@ -1,6 +1,6 @@ --- layout: default -title: Upgrading OpenSearch +title: OpenSearch Version Upgrades parent: Upgrade Overview nav_order: 10 redirect_from: @@ -14,7 +14,7 @@ This guide assumes that you are comfortable working from the Linux command line ### About this guide -Sample output and API responses included in this document were generated in a development environment. Testing was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. +Sample output and API responses included in this document were generated in a development environment. Testing was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. Sample terminal output and API responses are included for example purposes. Responses and terminal output for your OpenSearch cluster might look different. ### Prepare to upgrade From 1a8c4c07364f55c9441a025f2164e9e4664d6150 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Tue, 7 Feb 2023 13:44:52 -0800 Subject: [PATCH 16/54] Renaming the page to rolling upgrade since that is the only method being covered Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/version-upgrade.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/version-upgrade.md b/_install-and-configure/upgrade-opensearch/version-upgrade.md index 81e4eadfdc..7612348726 100644 --- a/_install-and-configure/upgrade-opensearch/version-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/version-upgrade.md @@ -1,30 +1,30 @@ --- layout: default -title: OpenSearch Version Upgrades -parent: Upgrade Overview +title: OpenSearch Version Upgrade +parent: Upgrading OpenSearch nav_order: 10 -redirect_from: - - /upgrade-opensearch/version-upgrade/ --- -# OpenSearch Version Upgrades +# OpenSearch Rolling Upgrade This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. {:.note} ### About this guide -Sample output and API responses included in this document were generated in a development environment. Testing was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. Sample terminal output and API responses are included for example purposes. Responses and terminal output for your OpenSearch cluster might look different. +Sample output and API responses included in this document were generated in a development environment. Testing and validation was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. Sample terminal output and API responses are included for example purposes and your terminal output and API responses may look slightly different. ### Prepare to upgrade -Before you upgrade, review [Upgrade Overview]({{site.url}}{{site.baseurl}}/upgrade-opensearch/index/) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. +Before you upgrade, review [Upgrading OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-opensearch/index/) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. {: .note} ### Rolling upgrade + + 1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. ```bash curl -X POST "http://localhost:9200/_flush?pretty" From 94705de37fa8bab9c9e69b92738caea07cea52d2 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 8 Feb 2023 09:16:56 -0800 Subject: [PATCH 17/54] Working through top-to-bottom now Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/version-upgrade.md | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/version-upgrade.md b/_install-and-configure/upgrade-opensearch/version-upgrade.md index 7612348726..ac6721b69c 100644 --- a/_install-and-configure/upgrade-opensearch/version-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/version-upgrade.md @@ -7,38 +7,24 @@ nav_order: 10 # OpenSearch Rolling Upgrade +Rolling upgrades, sometimes referred to as "node replacement upgrades," can be performed on running clusters with virtually no downtime. Nodes are dismissed from the cluster and replaced one at a time by nodes running the target version. During this process you can continue to index and query data in your cluster. + This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. {:.note} ### About this guide -Sample output and API responses included in this document were generated in a development environment. Testing and validation was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. Sample terminal output and API responses are included for example purposes and your terminal output and API responses may look slightly different. +The sample outputs and API responses included in this document were generated in a development environment. Testing and validation was performed by upgrading an Elasticsearch 7.10.2 cluster of 4 nodes to OpenSearch 1.3.7. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. ### Prepare to upgrade -Before you upgrade, review [Upgrading OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-opensearch/index/) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. +Review [Upgrading OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-opensearch/index/) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. {: .note} ### Rolling upgrade - - -1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. -```bash -curl -X POST "http://localhost:9200/_flush?pretty" -``` -**Sample response:** -```bash -{ - "_shards" : { - "total" : 4, - "successful" : 4, - "failed" : 0 - } -} -``` 1. Disable shard replication to prevent shard replicas from being created while nodes are being taken offline. ```bash curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' @@ -59,6 +45,20 @@ curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: a "transient" : { } } ``` +1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. This +```bash +curl -X POST "http://localhost:9200/_flush?pretty" +``` +**Sample response:** +```bash +{ + "_shards" : { + "total" : 4, + "successful" : 4, + "failed" : 0 + } +} +``` 1. Verify the health of your OpenSearch cluster. ```bash curl "http://localhost:9200/_cluster/health?pretty" From 00111f39eb66379ccdfdfbad4c56ac1bf1870b24 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 8 Feb 2023 09:27:42 -0800 Subject: [PATCH 18/54] Got the beginning steps re-ordered to make more sense and added some narrative to explain the steps Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/version-upgrade.md | 55 +++++++++---------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/version-upgrade.md b/_install-and-configure/upgrade-opensearch/version-upgrade.md index ac6721b69c..e4e266cb19 100644 --- a/_install-and-configure/upgrade-opensearch/version-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/version-upgrade.md @@ -25,9 +25,34 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y ### Rolling upgrade +1. Verify the health of your OpenSearch cluster before you begin. You should resolve any index or shard allocation issues prior to upgrading to ensure that your data is preserved. +```bash +curl "http://localhost:9201/_cluster/health?pretty" +``` +A status of **green** indicates that all primary and replica shards are allocated. See [Cluster health]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-health/) for more information. +**Sample response:** +```bash +{ + "cluster_name" : "opensearch-dev-cluster", + "status" : "green", + "timed_out" : false, + "number_of_nodes" : 4, + "number_of_data_nodes" : 4, + "active_primary_shards" : 1, + "active_shards" : 4, + "relocating_shards" : 0, + "initializing_shards" : 0, + "unassigned_shards" : 0, + "delayed_unassigned_shards" : 0, + "number_of_pending_tasks" : 0, + "number_of_in_flight_fetch" : 0, + "task_max_waiting_in_queue_millis" : 0, + "active_shards_percent_as_number" : 100.0 +} +``` 1. Disable shard replication to prevent shard replicas from being created while nodes are being taken offline. ```bash -curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' +curl -X PUT "http://localhost:9201/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' ``` **Sample response:** ```bash @@ -47,7 +72,7 @@ curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: a ``` 1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. This ```bash -curl -X POST "http://localhost:9200/_flush?pretty" +curl -X POST "http://localhost:9201/_flush?pretty" ``` **Sample response:** ```bash @@ -59,32 +84,6 @@ curl -X POST "http://localhost:9200/_flush?pretty" } } ``` -1. Verify the health of your OpenSearch cluster. -```bash -curl "http://localhost:9200/_cluster/health?pretty" -``` -A status of **green** indicates that all primary and replica shards are allocated. -**Sample response:** -```bash -{ - "cluster_name" : "opensearch-dev-cluster", - "status" : "green", - "timed_out" : false, - "number_of_nodes" : 4, - "number_of_data_nodes" : 4, - "discovered_master" : true, - "active_primary_shards" : 2, - "active_shards" : 4, - "relocating_shards" : 0, - "initializing_shards" : 0, - "unassigned_shards" : 0, - "delayed_unassigned_shards" : 0, - "number_of_pending_tasks" : 0, - "number_of_in_flight_fetch" : 0, - "task_max_waiting_in_queue_millis" : 0, - "active_shards_percent_as_number" : 100.0 -} -``` 1. List the running containers in your OpenSearch cluster and make a note of the container IDs and names. ```bash docker container ls From 56cd46fec7e9cc6592593b767c322fb20f1f4a20 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 8 Feb 2023 11:49:26 -0800 Subject: [PATCH 19/54] Wrapped up the technical steps and indented all content in the numbered list Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/version-upgrade.md | 379 +++++++++--------- 1 file changed, 197 insertions(+), 182 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/version-upgrade.md b/_install-and-configure/upgrade-opensearch/version-upgrade.md index e4e266cb19..ef01d4eb7d 100644 --- a/_install-and-configure/upgrade-opensearch/version-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/version-upgrade.md @@ -25,192 +25,207 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y ### Rolling upgrade -1. Verify the health of your OpenSearch cluster before you begin. You should resolve any index or shard allocation issues prior to upgrading to ensure that your data is preserved. -```bash -curl "http://localhost:9201/_cluster/health?pretty" -``` -A status of **green** indicates that all primary and replica shards are allocated. See [Cluster health]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-health/) for more information. -**Sample response:** -```bash -{ - "cluster_name" : "opensearch-dev-cluster", - "status" : "green", - "timed_out" : false, - "number_of_nodes" : 4, - "number_of_data_nodes" : 4, - "active_primary_shards" : 1, - "active_shards" : 4, - "relocating_shards" : 0, - "initializing_shards" : 0, - "unassigned_shards" : 0, - "delayed_unassigned_shards" : 0, - "number_of_pending_tasks" : 0, - "number_of_in_flight_fetch" : 0, - "task_max_waiting_in_queue_millis" : 0, - "active_shards_percent_as_number" : 100.0 -} -``` -1. Disable shard replication to prevent shard replicas from being created while nodes are being taken offline. -```bash -curl -X PUT "http://localhost:9201/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' -``` -**Sample response:** -```bash -{ - "acknowledged" : true, - "persistent" : { - "cluster" : { - "routing" : { - "allocation" : { - "enable" : "primaries" +1. Verify the health of your OpenSearch cluster before you begin. You should resolve any index or shard allocation issues prior to upgrading to ensure that your data is preserved. A status of **green** indicates that all primary and replica shards are allocated. See [Cluster health]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-health/) for more information. + ```bash + curl "http://localhost:9201/_cluster/health?pretty" + ``` + **Sample response:** + ```bash + { + "cluster_name" : "opensearch-dev-cluster", + "status" : "green", + "timed_out" : false, + "number_of_nodes" : 4, + "number_of_data_nodes" : 4, + "active_primary_shards" : 1, + "active_shards" : 4, + "relocating_shards" : 0, + "initializing_shards" : 0, + "unassigned_shards" : 0, + "delayed_unassigned_shards" : 0, + "number_of_pending_tasks" : 0, + "number_of_in_flight_fetch" : 0, + "task_max_waiting_in_queue_millis" : 0, + "active_shards_percent_as_number" : 100.0 + } + ``` +1. Disable shard replication to prevent shard replicas from being created while nodes are being taken offline. This stops the movement of Lucene index segments on nodes in your cluster. + ```bash + curl -X PUT "http://localhost:9201/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' + ``` + **Sample response:** + ```bash + { + "acknowledged" : true, + "persistent" : { + "cluster" : { + "routing" : { + "allocation" : { + "enable" : "primaries" + } } } + }, + "transient" : { } + } + ``` +1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. + ```bash + curl -X POST "http://localhost:9201/_flush?pretty" + ``` + **Sample response:** + ```bash + { + "_shards" : { + "total" : 4, + "successful" : 4, + "failed" : 0 } - }, - "transient" : { } -} -``` -1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. This -```bash -curl -X POST "http://localhost:9201/_flush?pretty" -``` -**Sample response:** -```bash -{ - "_shards" : { - "total" : 4, - "successful" : 4, - "failed" : 0 } -} -``` -1. List the running containers in your OpenSearch cluster and make a note of the container IDs and names. -```bash -docker container ls -``` -**Sample output:** -```bash -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -af1ec1c3fef7 opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-04 -1d47c0da60ad opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-03 -f553b5ec870b opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-02 -934e4325d9a4 opensearchproject/opensearch:1.3.7 "./opensearch-docker…" 4 minutes ago Up 4 minutes 9300/tcp, 9650/tcp, 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp os-node-01 -``` -1. Query `_cat/nodes` to determine which node is operating as the cluster manager. Note that OpenSearch 1.x versions use the heading "master," which has been deprecated and replaced by "cluster_manager" in OpenSearch 2.x versions. -```bash -curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t -``` -**Sample output:** -```bash -name version node.role master -os-node-03 1.3.7 dimr - -os-node-04 1.3.7 dimr - -os-node-01 1.3.7 dimr - -os-node-02 1.3.7 dimr * -``` -1. Select a node to upgrade first. Cluster manager-eligible nodes should be upgraded last because nodes cannot join an OpenSearch cluster if they are running an older version of OpenSearch than the elected cluster manager. -```bash -docker stop && docker container rm -``` -**Sample output:** -```bash -$ docker stop 934e4325d9a4 && docker rm 934e4325d9a4 -934e4325d9a4 -934e4325d9a4 -``` -**Important:** Do not delete the volume associated with the container when you delete the container. The new OpenSearch container will use the existing volume. Deleting the volume will result in data loss. + ``` +1. Review your cluster and identify the first node to upgrade. Eligible cluster manager nodes should be upgraded last because OpenSearch nodes can join a cluster with manager nodes running an older version, but they cannot join a cluster with all manager nodes running a newer version. + ```bash + docker container ls + ``` + **Sample output:** + ```bash + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + a50a9617991b docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9204->9200/tcp, :::9204->9200/tcp, 0.0.0.0:9604->9600/tcp, :::9604->9600/tcp os-node-04 + fac35167fcbd docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9203->9200/tcp, :::9203->9200/tcp, 0.0.0.0:9603->9600/tcp, :::9603->9600/tcp os-node-03 + fa4efbe64cbf docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9202->9200/tcp, :::9202->9200/tcp, 0.0.0.0:9602->9600/tcp, :::9602->9600/tcp os-node-02 + 17e898d67ac2 docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9201->9200/tcp, :::9201->9200/tcp, 0.0.0.0:9601->9600/tcp, :::9601->9600/tcp os-node-01 + ``` +1. Query `_cat/nodes` to verify which node has been elected as cluster manager. Note that OpenSearch 1.x versions use the heading "master," which has been deprecated and replaced by "cluster_manager" in OpenSearch 2.x and later. + ```bash + curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t + ``` + Sample output: + ```bash + name version node.role master + os-node-01 7.10.2 dimr - + os-node-04 7.10.2 dimr - + os-node-03 7.10.2 dimr - + os-node-02 7.10.2 dimr * + ``` +1. Stop the node you are upgrading. + ```bash + docker stop && docker container rm + ``` + Sample output: + ```bash + $ docker stop os-node-01 && docker container rm os-node-01 + os-node-01 + os-node-01 + ``` + **Important:** Do not delete the volume associated with the container when you delete the container. The new OpenSearch container will use the existing volume. **Deleting the volume will result in data loss.** 1. Confirm that the associated node has been dismissed from the cluster. -```bash -curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t -``` -**Sample output:** -```bash -name version node.role master -os-node-03 1.3.7 dimr - -os-node-04 1.3.7 dimr - -os-node-02 1.3.7 dimr * -``` -`os-node-01` is no longer listed because the container has been stopped and deleted. -1. Deploy a new container running the desired version of OpenSearch, mapped to the same volume as the container you deleted. -```bash -docker run -d \ - -p 9200:9200 -p 9600:9600 \ - -e "discovery.seed_hosts=os-node-01,os-node-02,os-node-03,os-node-04" -e "DISABLE_SECURITY_PLUGIN=true" \ - -e "DISABLE_INSTALL_DEMO_CONFIG=true" -e "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" \ - -e "cluster.name=opensearch-dev-cluster" -e "node.name=os-node-01" \ - -e "cluster.initial_cluster_manager_nodes=os-node-01,os-node-02,os-node-03,os-node-04" \ - -e "bootstrap.memory_lock=true" -e "path.repo=/mnt/snapshots" \ - --ulimit nofile=65536:65536 --ulimit memlock=-1:-1 \ - -v os-data-01:/usr/share/opensearch/data \ - -v /Users/username/Documents/opensearch/snapshots/repo-01:/mnt/snapshots \ - --network opensearch-dev-net \ - --name os-node-01 \ - opensearchproject/opensearch:2.4.1 -``` -**Sample output:** -```bash -778e33168157e39814cb66ff81523c9d40772d122472c718bb3839e0c365cfe2 -``` -1. Give the new container time to start, then query `_cat/nodes` to confirm that the new node has joined the cluster, and that it is running the desired version of OpenSearch. -```bash -curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t -``` -**Sample output:** -```bash -name version node.role master -os-node-03 1.3.7 dimr - -os-node-04 1.3.7 dimr - -os-node-02 1.3.7 dimr * -os-node-01 2.4.1 dimr - -``` -1. Repeat steps 5 through 9 for each node in your cluster. Remember to upgrade an eligible cluster manager node last. When you are finished replacing the last node, query `_cat/nodes` to confirm that all nodes have joined the cluster and are running the desired version of OpenSearch. -```bash -curl -s "http://localhost:9200/_cat/nodes?v&h=name,version,node.role,master" | column -t -``` -**Sample output:** -```bash -name version node.role master -os-node-02 2.4.1 dimr - -os-node-03 2.4.1 dimr * -os-node-04 2.4.1 dimr - -os-node-01 2.4.1 dimr - -``` -There are no longer any cluster manager-eligible nodes running the old version, so a cluster manager running the new version is elected. The cluster has now been bootstrapped with the new version. + ```bash + curl -s "http://localhost:9202/_cat/nodes?v&h=name,version,node.role,master" | column -t + ``` + Sample output: + ```bash + name version node.role master + os-node-02 7.10.2 dimr * + os-node-04 7.10.2 dimr - + os-node-03 7.10.2 dimr - + ``` + `os-node-01` is no longer listed because the container has been stopped and deleted. +1. Deploy a new container running the desired version of OpenSearch, mapped to the same volume as the container you deleted. The command used in the dev environment is included below. + ```bash + docker run -d \ + -p 9201:9200 -p 9601:9600 \ + -e "discovery.seed_hosts=os-node-01,os-node-02,os-node-03,os-node-04" -e "DISABLE_SECURITY_PLUGIN=true" \ + -e "DISABLE_INSTALL_DEMO_CONFIG=true" -e "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" \ + -e "cluster.name=opensearch-dev-cluster" -e "node.name=os-node-01" \ + -e "cluster.initial_master_nodes=os-node-01,os-node-02,os-node-03,os-node-04" \ + -e "bootstrap.memory_lock=true" -e "path.repo=/mnt/snapshots" \ + --ulimit nofile=65536:65536 --ulimit memlock=-1:-1 \ + -v data-01:/usr/share/opensearch/data \ + -v repo-01:/mnt/snapshots \ + --network opensearch-dev-net \ + --name os-node-01 \ + opensearchproject/opensearch:1.3.7 + ``` + Sample output: + ```bash + b6d06de7a016aa3bb76c133c55ba4e0e605f522c7a6a4ebd2aa6c6a6d3f49728 + ``` +1. Query the `_cat/nodes` endpoint after OpenSearch is running on the new node to confirm that it has joined the cluster. + ```bash + curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t + ``` + Sample output: + ```bash + name version node.role master + os-node-02 7.10.2 dimr * + os-node-04 7.10.2 dimr - + os-node-01 7.10.2 dimr - + os-node-03 7.10.2 dimr - + ``` + In the sample output, the new OpenSearch node reports a running version of `7.10.2` to the cluster for compatibility purposes. You can manually confirm the version by reviewing the output of the `/_nodes` API endpoint, like the following command. Replace `` with the name of your node. See [Nodes API]({{site.url}}{{site.baseurl}}/latest/api-reference/nodes-apis/index/) to learn more. + ```bash + curl -s -X GET 'localhost:9201/_nodes/?pretty=true' | jq -r '.nodes | .[] | "\(.name) v\(.version)"' + ``` + Sample output: + ```bash + $ curl -s -X GET 'localhost:9201/_nodes/os-node-01?pretty=true' | jq -r '.nodes | .[] | "\(.name) v\(.version)"' + os-node-01 v1.3.7 + ``` +1. Repeat steps 5 through 9 for each node in your cluster. Remember to upgrade an eligible cluster manager node last. When you are finished replacing the last node, query `_cat/nodes` to confirm that all nodes have joined the cluster. The cluster is now bootstrapped to the new version of OpenSearch. + ```bash + curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t + ``` + Sample output: + ```bash + name version node.role master + os-node-04 1.3.7 dimr - + os-node-02 1.3.7 dimr * + os-node-01 1.3.7 dimr - + os-node-03 1.3.7 dimr - + ``` + There are no longer any eligible cluster manager nodes running the old version, so a cluster manager running the new version was elected. The cluster has now been bootstrapped to the new version. 1. Reenable shard replication. -```bash -curl -X PUT "http://localhost:9200/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":null}}' -``` -**Sample output:** -```bash -{ - "acknowledged" : true, - "persistent" : { }, - "transient" : { } -} -``` + ```bash + curl -X PUT "http://localhost:9201/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"all"}}' + ``` + Sample output: + ```bash + { + "acknowledged" : true, + "persistent" : { + "cluster" : { + "routing" : { + "allocation" : { + "enable" : "all" + } + } + } + }, + "transient" : { } + } + ``` 1. Confirm that the cluster is healthy. -```bash -curl "http://localhost:9200/_cluster/health?pretty" -``` -**Sample output:** -```bash -{ - "cluster_name" : "opensearch-dev-cluster", - "status" : "green", - "timed_out" : false, - "number_of_nodes" : 4, - "number_of_data_nodes" : 4, - "discovered_master" : true, - "discovered_cluster_manager" : true, - "active_primary_shards" : 2, - "active_shards" : 4, - "relocating_shards" : 0, - "initializing_shards" : 0, - "unassigned_shards" : 0, - "delayed_unassigned_shards" : 0, - "number_of_pending_tasks" : 0, - "number_of_in_flight_fetch" : 0, - "task_max_waiting_in_queue_millis" : 0, - "active_shards_percent_as_number" : 100.0 -} -```version- \ No newline at end of file + ```bash + curl "http://localhost:9201/_cluster/health?pretty" + ``` + Sample output: + ```bash + { + "cluster_name" : "opensearch-dev-cluster", + "status" : "green", + "timed_out" : false, + "number_of_nodes" : 4, + "number_of_data_nodes" : 4, + "discovered_master" : true, + "active_primary_shards" : 1, + "active_shards" : 4, + "relocating_shards" : 0, + "initializing_shards" : 0, + "unassigned_shards" : 0, + "delayed_unassigned_shards" : 0, + "number_of_pending_tasks" : 0, + "number_of_in_flight_fetch" : 0, + "task_max_waiting_in_queue_millis" : 0, + "active_shards_percent_as_number" : 100.0 + } + ``` From 98cad43eb5b9b068a0c3bc9c3857c7f683203d72 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 8 Feb 2023 12:44:03 -0800 Subject: [PATCH 20/54] Renamed upgrade page to make more relevant Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 4 ---- .../{version-upgrade.md => rolling-upgrade.md} | 12 ++++++------ 2 files changed, 6 insertions(+), 10 deletions(-) rename _install-and-configure/upgrade-opensearch/{version-upgrade.md => rolling-upgrade.md} (99%) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 3e59c25ffc..84a5fbac74 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -15,10 +15,6 @@ OpenSearch nodes and indexes are backwards-compatible by one major version. That The following table can be used as a reference for Lucene versions running in OpenSearch 1.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. -{% comment %} -The following table needs some love. There's an issue with the CSS (I think) that's not drawing a right border for tr:last-child -{% endcomment %} - If your upgrade path spans more than a single major version, and you want to maintain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. ## Workflow considerations diff --git a/_install-and-configure/upgrade-opensearch/version-upgrade.md b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md similarity index 99% rename from _install-and-configure/upgrade-opensearch/version-upgrade.md rename to _install-and-configure/upgrade-opensearch/rolling-upgrade.md index ef01d4eb7d..92f20df36a 100644 --- a/_install-and-configure/upgrade-opensearch/version-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md @@ -1,6 +1,6 @@ --- layout: default -title: OpenSearch Version Upgrade +title: OpenSearch Rolling Upgrade parent: Upgrading OpenSearch nav_order: 10 --- @@ -30,7 +30,7 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y curl "http://localhost:9201/_cluster/health?pretty" ``` **Sample response:** - ```bash + ```json { "cluster_name" : "opensearch-dev-cluster", "status" : "green", @@ -54,7 +54,7 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y curl -X PUT "http://localhost:9201/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' ``` **Sample response:** - ```bash + ```json { "acknowledged" : true, "persistent" : { @@ -74,7 +74,7 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y curl -X POST "http://localhost:9201/_flush?pretty" ``` **Sample response:** - ```bash + ```json { "_shards" : { "total" : 4, @@ -189,7 +189,7 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y curl -X PUT "http://localhost:9201/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"all"}}' ``` Sample output: - ```bash + ```json { "acknowledged" : true, "persistent" : { @@ -209,7 +209,7 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y curl "http://localhost:9201/_cluster/health?pretty" ``` Sample output: - ```bash + ```json { "cluster_name" : "opensearch-dev-cluster", "status" : "green", From 876ddd28405a681e9b0a9781b305e21f0b02154e Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 8 Feb 2023 12:57:07 -0800 Subject: [PATCH 21/54] Tweaking toc Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 84a5fbac74..a41f599c34 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -1,7 +1,7 @@ --- layout: default title: Upgrading OpenSearch -nav_order: 1 +nav_order: 4 has_children: true redirect_from: - /upgrade-opensearch/index/ From 37609133fad6b1aea4e23b61511e945e26ccd1a5 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Wed, 8 Feb 2023 13:31:46 -0800 Subject: [PATCH 22/54] Fixed markdown block formatting in rolling restart page Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/rolling-upgrade.md | 388 +++++++++--------- 1 file changed, 194 insertions(+), 194 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md index 92f20df36a..113fd163fb 100644 --- a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md @@ -1,11 +1,11 @@ --- layout: default -title: OpenSearch Rolling Upgrade +title: Rolling Upgrade parent: Upgrading OpenSearch nav_order: 10 --- -# OpenSearch Rolling Upgrade +# Rolling Upgrade Rolling upgrades, sometimes referred to as "node replacement upgrades," can be performed on running clusters with virtually no downtime. Nodes are dismissed from the cluster and replaced one at a time by nodes running the target version. During this process you can continue to index and query data in your cluster. @@ -26,206 +26,206 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y ### Rolling upgrade 1. Verify the health of your OpenSearch cluster before you begin. You should resolve any index or shard allocation issues prior to upgrading to ensure that your data is preserved. A status of **green** indicates that all primary and replica shards are allocated. See [Cluster health]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-health/) for more information. - ```bash - curl "http://localhost:9201/_cluster/health?pretty" - ``` - **Sample response:** - ```json - { - "cluster_name" : "opensearch-dev-cluster", - "status" : "green", - "timed_out" : false, - "number_of_nodes" : 4, - "number_of_data_nodes" : 4, - "active_primary_shards" : 1, - "active_shards" : 4, - "relocating_shards" : 0, - "initializing_shards" : 0, - "unassigned_shards" : 0, - "delayed_unassigned_shards" : 0, - "number_of_pending_tasks" : 0, - "number_of_in_flight_fetch" : 0, - "task_max_waiting_in_queue_millis" : 0, - "active_shards_percent_as_number" : 100.0 - } - ``` + ```bash + curl "http://localhost:9201/_cluster/health?pretty" + ``` + Sample output: + ```json + { + "cluster_name":"opensearch-dev-cluster", + "status":"green", + "timed_out":false, + "number_of_nodes":4, + "number_of_data_nodes":4, + "active_primary_shards":1, + "active_shards":4, + "relocating_shards":0, + "initializing_shards":0, + "unassigned_shards":0, + "delayed_unassigned_shards":0, + "number_of_pending_tasks":0, + "number_of_in_flight_fetch":0, + "task_max_waiting_in_queue_millis":0, + "active_shards_percent_as_number":100.0 + } + ``` 1. Disable shard replication to prevent shard replicas from being created while nodes are being taken offline. This stops the movement of Lucene index segments on nodes in your cluster. - ```bash - curl -X PUT "http://localhost:9201/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' - ``` - **Sample response:** - ```json - { - "acknowledged" : true, - "persistent" : { - "cluster" : { - "routing" : { - "allocation" : { - "enable" : "primaries" - } - } - } - }, - "transient" : { } - } - ``` + ```bash + curl -X PUT "http://localhost:9201/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"primaries"}}' + ``` + Sample output: + ```json + { + "acknowledged" : true, + "persistent" : { + "cluster" : { + "routing" : { + "allocation" : { + "enable" : "primaries" + } + } + } + }, + "transient" : { } + } + ``` 1. Perform a flush operation on the cluster to commit transaction log entries to the Lucene index. - ```bash - curl -X POST "http://localhost:9201/_flush?pretty" - ``` - **Sample response:** - ```json - { - "_shards" : { - "total" : 4, - "successful" : 4, - "failed" : 0 - } - } - ``` + ```bash + curl -X POST "http://localhost:9201/_flush?pretty" + ``` + Sample output: + ```json + { + "_shards" : { + "total" : 4, + "successful" : 4, + "failed" : 0 + } + } + ``` 1. Review your cluster and identify the first node to upgrade. Eligible cluster manager nodes should be upgraded last because OpenSearch nodes can join a cluster with manager nodes running an older version, but they cannot join a cluster with all manager nodes running a newer version. - ```bash - docker container ls - ``` - **Sample output:** - ```bash - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - a50a9617991b docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9204->9200/tcp, :::9204->9200/tcp, 0.0.0.0:9604->9600/tcp, :::9604->9600/tcp os-node-04 - fac35167fcbd docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9203->9200/tcp, :::9203->9200/tcp, 0.0.0.0:9603->9600/tcp, :::9603->9600/tcp os-node-03 - fa4efbe64cbf docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9202->9200/tcp, :::9202->9200/tcp, 0.0.0.0:9602->9600/tcp, :::9602->9600/tcp os-node-02 - 17e898d67ac2 docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9201->9200/tcp, :::9201->9200/tcp, 0.0.0.0:9601->9600/tcp, :::9601->9600/tcp os-node-01 - ``` + ```bash + docker container ls + ``` + Sample output: + ```bash + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + a50a9617991b docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9204->9200/tcp, :::9204->9200/tcp, 0.0.0.0:9604->9600/tcp, :::9604->9600/tcp os-node-04 + fac35167fcbd docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9203->9200/tcp, :::9203->9200/tcp, 0.0.0.0:9603->9600/tcp, :::9603->9600/tcp os-node-03 + fa4efbe64cbf docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9202->9200/tcp, :::9202->9200/tcp, 0.0.0.0:9602->9600/tcp, :::9602->9600/tcp os-node-02 + 17e898d67ac2 docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9201->9200/tcp, :::9201->9200/tcp, 0.0.0.0:9601->9600/tcp, :::9601->9600/tcp os-node-01 + ``` 1. Query `_cat/nodes` to verify which node has been elected as cluster manager. Note that OpenSearch 1.x versions use the heading "master," which has been deprecated and replaced by "cluster_manager" in OpenSearch 2.x and later. - ```bash - curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t - ``` - Sample output: - ```bash - name version node.role master - os-node-01 7.10.2 dimr - - os-node-04 7.10.2 dimr - - os-node-03 7.10.2 dimr - - os-node-02 7.10.2 dimr * - ``` + ```bash + curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t + ``` + Sample output: + ```bash + name version node.role master + os-node-01 7.10.2 dimr - + os-node-04 7.10.2 dimr - + os-node-03 7.10.2 dimr - + os-node-02 7.10.2 dimr * + ``` 1. Stop the node you are upgrading. - ```bash - docker stop && docker container rm - ``` - Sample output: - ```bash - $ docker stop os-node-01 && docker container rm os-node-01 - os-node-01 - os-node-01 - ``` - **Important:** Do not delete the volume associated with the container when you delete the container. The new OpenSearch container will use the existing volume. **Deleting the volume will result in data loss.** + ```bash + docker stop && docker container rm + ``` + Sample output: + ```bash + $ docker stop os-node-01 && docker container rm os-node-01 + os-node-01 + os-node-01 + ``` + **Important:** Do not delete the volume associated with the container when you delete the container. The new OpenSearch container will use the existing volume. **Deleting the volume will result in data loss.** 1. Confirm that the associated node has been dismissed from the cluster. - ```bash - curl -s "http://localhost:9202/_cat/nodes?v&h=name,version,node.role,master" | column -t - ``` - Sample output: - ```bash - name version node.role master - os-node-02 7.10.2 dimr * - os-node-04 7.10.2 dimr - - os-node-03 7.10.2 dimr - - ``` - `os-node-01` is no longer listed because the container has been stopped and deleted. + ```bash + curl -s "http://localhost:9202/_cat/nodes?v&h=name,version,node.role,master" | column -t + ``` + Sample output: + ```bash + name version node.role master + os-node-02 7.10.2 dimr * + os-node-04 7.10.2 dimr - + os-node-03 7.10.2 dimr - + ``` + `os-node-01` is no longer listed because the container has been stopped and deleted. 1. Deploy a new container running the desired version of OpenSearch, mapped to the same volume as the container you deleted. The command used in the dev environment is included below. - ```bash - docker run -d \ - -p 9201:9200 -p 9601:9600 \ - -e "discovery.seed_hosts=os-node-01,os-node-02,os-node-03,os-node-04" -e "DISABLE_SECURITY_PLUGIN=true" \ - -e "DISABLE_INSTALL_DEMO_CONFIG=true" -e "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" \ - -e "cluster.name=opensearch-dev-cluster" -e "node.name=os-node-01" \ - -e "cluster.initial_master_nodes=os-node-01,os-node-02,os-node-03,os-node-04" \ - -e "bootstrap.memory_lock=true" -e "path.repo=/mnt/snapshots" \ - --ulimit nofile=65536:65536 --ulimit memlock=-1:-1 \ - -v data-01:/usr/share/opensearch/data \ - -v repo-01:/mnt/snapshots \ - --network opensearch-dev-net \ - --name os-node-01 \ - opensearchproject/opensearch:1.3.7 - ``` - Sample output: - ```bash - b6d06de7a016aa3bb76c133c55ba4e0e605f522c7a6a4ebd2aa6c6a6d3f49728 - ``` + ```bash + docker run -d \ + -p 9201:9200 -p 9601:9600 \ + -e "discovery.seed_hosts=os-node-01,os-node-02,os-node-03,os-node-04" -e "DISABLE_SECURITY_PLUGIN=true" \ + -e "DISABLE_INSTALL_DEMO_CONFIG=true" -e "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" \ + -e "cluster.name=opensearch-dev-cluster" -e "node.name=os-node-01" \ + -e "cluster.initial_master_nodes=os-node-01,os-node-02,os-node-03,os-node-04" \ + -e "bootstrap.memory_lock=true" -e "path.repo=/mnt/snapshots" \ + --ulimit nofile=65536:65536 --ulimit memlock=-1:-1 \ + -v data-01:/usr/share/opensearch/data \ + -v repo-01:/mnt/snapshots \ + --network opensearch-dev-net \ + --name os-node-01 \ + opensearchproject/opensearch:1.3.7 + ``` + Sample output: + ```bash + b6d06de7a016aa3bb76c133c55ba4e0e605f522c7a6a4ebd2aa6c6a6d3f49728 + ``` 1. Query the `_cat/nodes` endpoint after OpenSearch is running on the new node to confirm that it has joined the cluster. - ```bash - curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t - ``` - Sample output: - ```bash - name version node.role master - os-node-02 7.10.2 dimr * - os-node-04 7.10.2 dimr - - os-node-01 7.10.2 dimr - - os-node-03 7.10.2 dimr - - ``` - In the sample output, the new OpenSearch node reports a running version of `7.10.2` to the cluster for compatibility purposes. You can manually confirm the version by reviewing the output of the `/_nodes` API endpoint, like the following command. Replace `` with the name of your node. See [Nodes API]({{site.url}}{{site.baseurl}}/latest/api-reference/nodes-apis/index/) to learn more. - ```bash - curl -s -X GET 'localhost:9201/_nodes/?pretty=true' | jq -r '.nodes | .[] | "\(.name) v\(.version)"' - ``` - Sample output: - ```bash - $ curl -s -X GET 'localhost:9201/_nodes/os-node-01?pretty=true' | jq -r '.nodes | .[] | "\(.name) v\(.version)"' - os-node-01 v1.3.7 - ``` + ```bash + curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t + ``` + Sample output: + ```bash + name version node.role master + os-node-02 7.10.2 dimr * + os-node-04 7.10.2 dimr - + os-node-01 7.10.2 dimr - + os-node-03 7.10.2 dimr - + ``` + In the sample output, the new OpenSearch node reports a running version of `7.10.2` to the cluster for compatibility purposes. You can manually confirm the version by reviewing the output of the `/_nodes` API endpoint, like the following command. Replace `` with the name of your node. See [Nodes API]({{site.url}}{{site.baseurl}}/latest/api-reference/nodes-apis/index/) to learn more. + ``` + curl -s -X GET 'localhost:9201/_nodes/?pretty=true' | jq -r '.nodes | .[] | "\(.name) v\(.version)"' + ``` + Sample output: + ``` + $ curl -s -X GET 'localhost:9201/_nodes/os-node-01?pretty=true' | jq -r '.nodes | .[] | "\(.name) v\(.version)"' + os-node-01 v1.3.7 + ``` 1. Repeat steps 5 through 9 for each node in your cluster. Remember to upgrade an eligible cluster manager node last. When you are finished replacing the last node, query `_cat/nodes` to confirm that all nodes have joined the cluster. The cluster is now bootstrapped to the new version of OpenSearch. - ```bash - curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t - ``` - Sample output: - ```bash - name version node.role master - os-node-04 1.3.7 dimr - - os-node-02 1.3.7 dimr * - os-node-01 1.3.7 dimr - - os-node-03 1.3.7 dimr - - ``` - There are no longer any eligible cluster manager nodes running the old version, so a cluster manager running the new version was elected. The cluster has now been bootstrapped to the new version. + ```bash + curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t + ``` + Sample output: + ```bash + name version node.role master + os-node-04 1.3.7 dimr - + os-node-02 1.3.7 dimr * + os-node-01 1.3.7 dimr - + os-node-03 1.3.7 dimr - + ``` + There are no longer any eligible cluster manager nodes running the old version, so a cluster manager running the new version was elected. The cluster has now been bootstrapped to the new version. 1. Reenable shard replication. - ```bash - curl -X PUT "http://localhost:9201/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"all"}}' - ``` - Sample output: - ```json - { - "acknowledged" : true, - "persistent" : { - "cluster" : { - "routing" : { - "allocation" : { - "enable" : "all" - } - } - } - }, - "transient" : { } - } - ``` + ```bash + curl -X PUT "http://localhost:9201/_cluster/settings?pretty" -H 'Content-type: application/json' -d'{"persistent":{"cluster.routing.allocation.enable":"all"}}' + ``` + Sample output: + ```json + { + "acknowledged" : true, + "persistent" : { + "cluster" : { + "routing" : { + "allocation" : { + "enable" : "all" + } + } + } + }, + "transient" : { } + } + ``` 1. Confirm that the cluster is healthy. - ```bash - curl "http://localhost:9201/_cluster/health?pretty" - ``` - Sample output: - ```json - { - "cluster_name" : "opensearch-dev-cluster", - "status" : "green", - "timed_out" : false, - "number_of_nodes" : 4, - "number_of_data_nodes" : 4, - "discovered_master" : true, - "active_primary_shards" : 1, - "active_shards" : 4, - "relocating_shards" : 0, - "initializing_shards" : 0, - "unassigned_shards" : 0, - "delayed_unassigned_shards" : 0, - "number_of_pending_tasks" : 0, - "number_of_in_flight_fetch" : 0, - "task_max_waiting_in_queue_millis" : 0, - "active_shards_percent_as_number" : 100.0 - } - ``` + ```bash + curl "http://localhost:9201/_cluster/health?pretty" + ``` + Sample output: + ```bash + { + "cluster_name" : "opensearch-dev-cluster", + "status" : "green", + "timed_out" : false, + "number_of_nodes" : 4, + "number_of_data_nodes" : 4, + "discovered_master" : true, + "active_primary_shards" : 1, + "active_shards" : 4, + "relocating_shards" : 0, + "initializing_shards" : 0, + "unassigned_shards" : 0, + "delayed_unassigned_shards" : 0, + "number_of_pending_tasks" : 0, + "number_of_in_flight_fetch" : 0, + "task_max_waiting_in_queue_millis" : 0, + "active_shards_percent_as_number" : 100.0 + } + ``` From 2c0eddaa47da70d39b663d300819e06c925447eb Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Thu, 9 Feb 2023 10:32:39 -0800 Subject: [PATCH 23/54] Working through upgrade intro and implementing technical feedback Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index a41f599c34..a33bf0b323 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -11,9 +11,9 @@ redirect_from: The OpenSearch Project releases regular updates that include new features, enhancements, and bug fixes. OpenSearch uses [Semantic Versioning](https://semver.org/), which means that breaking changes are only introduced between major version releases. To learn about upcoming features and fixes, review the [OpenSearch Project Roadmap](https://github.com/orgs/opensearch-project/projects/1) on GitHub. To see a list of previous releases, or to learn more about how OpenSearch uses versioning, check out the [Release Schedule and Maintenance Policy]({{site.url}}/releases.html). -OpenSearch nodes and indexes are backwards-compatible by one major version. That means, for example, that you can restore an index to an OpenSearch 2.4.1 cluster from a snapshot that was taken on an OpenSearch 1.x cluster. Index compatibility is determined by the version of OpenSearch or Lucene that created the index. If an index was created by an OpenSearch cluster running version 1.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. +OpenSearch nodes are compatible with nodes running any other minor version within the same major version release. For example, 1.1.0 is compatible with 1.3.7 because they are part of the same major version (1.x). Additionally, OpenSearch nodes and indexes are backwards-compatible with the previous major version (**N-1**). That means, for example, that an index created by an OpenSearch node running version 1.3.7 could be restored from a snapshot to an OpenSearch cluster running version 2.5.0. There are special considerations that should be taken into consideration if system indexes are also being restored. These considerations will be added as we continue to improve and expand this documentation. -The following table can be used as a reference for Lucene versions running in OpenSearch 1.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. +Index compatibility is determined by the version of [Apache Lucene](https://lucene.apache.org/) that created the index. If an index was created by an OpenSearch cluster running version 1.0.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. See the [Lucene version reference](#lucene-version-reference) table for Lucene versions running in OpenSearch 1.0.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. If your upgrade path spans more than a single major version, and you want to maintain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. @@ -164,7 +164,6 @@ td { - 7.11
7.10 - \ No newline at end of file From 899f9ac17f98149729a92311841db1b3504f844b Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Thu, 9 Feb 2023 10:33:00 -0800 Subject: [PATCH 24/54] Phrasing Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index a33bf0b323..6105982281 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -15,7 +15,7 @@ OpenSearch nodes are compatible with nodes running any other minor version withi Index compatibility is determined by the version of [Apache Lucene](https://lucene.apache.org/) that created the index. If an index was created by an OpenSearch cluster running version 1.0.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. See the [Lucene version reference](#lucene-version-reference) table for Lucene versions running in OpenSearch 1.0.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. -If your upgrade path spans more than a single major version, and you want to maintain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. +If your upgrade path spans more than a single major version, and you want to retain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. ## Workflow considerations From 571593fa47971afd1c9adc9111f51caa22d3a7fd Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Thu, 9 Feb 2023 10:37:55 -0800 Subject: [PATCH 25/54] Reviewing reindex guidance Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 6105982281..4e1f81bcec 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -15,7 +15,7 @@ OpenSearch nodes are compatible with nodes running any other minor version withi Index compatibility is determined by the version of [Apache Lucene](https://lucene.apache.org/) that created the index. If an index was created by an OpenSearch cluster running version 1.0.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. See the [Lucene version reference](#lucene-version-reference) table for Lucene versions running in OpenSearch 1.0.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. -If your upgrade path spans more than a single major version, and you want to retain existing indexes, then you will need to use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. +If your upgrade path spans more than a single major version, and you want to retain any existing index(es), then you can use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. One alternative to reindexing is to reingest data from the origin, such as by replaying a datastream or ingesting data from a database. ## Workflow considerations From 6f2bc42fc7fbfa992587e396f0d3d6a64ba4c62d Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Thu, 9 Feb 2023 10:59:27 -0800 Subject: [PATCH 26/54] Phrasing on compatibility to make tone more active Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 4e1f81bcec..f2484fda7d 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -19,7 +19,7 @@ If your upgrade path spans more than a single major version, and you want to ret ## Workflow considerations -You should take time to plan the process before making any changes to your cluster. For example, consider how long the upgrade process will take. If your cluster is being used in production, how impactful is downtime? Do you have infrastructure in place to stand up the new cluster in a dev environment before you move it into production, or do you need to upgrade the hosts in-place? The answers to questions like these will help you determine which upgrade path will work best in your environment. At a minimum, you should: +Take time to plan the process before making any changes to your cluster. For example, consider how long the upgrade process will take. If your cluster is being used in production, how impactful is downtime? Do you have infrastructure in-place to stand up the new cluster in a testing or development environment before you move it into production, or do you need to upgrade the production hosts directly? The answers to questions like these will help you determine which upgrade path will work best in your environment. At a minimum, you should: - [Review breaking changes](#review-breaking-changes) - [Review the OpenSearch tools compatibility matrices](#review-the-opensearch-tools-compatibility-matrices) @@ -27,23 +27,20 @@ You should take time to plan the process before making any changes to your clust - [Back up configuration files](#back-up-configuration-files) - [Create a snapshot](#create-a-snapshot) -Before upgrading your production cluster, test the new version of OpenSearch in a development environment to validate functionality and compatibility with components in your production workflow. -{: .tip} - Stop any non-essential indexing before you begin the upgrade procedure. {: .tip} ### Review breaking changes -It's important to determine how the new version of OpenSearch will fit into your production environment. Review the list of [breaking changes]({{site.url}}{{site.baseurl}}/breaking-changes/) before beginning any upgrade procedures to determine if you will need to make adjustments in your workflow. For example, upstream or downstream components might need to be adjusted to take an API change into account. +It's important to determine how the new version of OpenSearch will fit into your production environment. Review [Breaking changes]({{site.url}}{{site.baseurl}}/breaking-changes/) before beginning any upgrade procedures to determine if you will need to make adjustments in your workflow. For example, upstream or downstream components might need to be adjusted due to an API change. ### Review the OpenSearch tools compatibility matrices -Your OpenSearch cluster may interact with other services in your environment, like Logstash or Beats. Check the [OpenSearch tools compatibility matrices]({{site.url}}{{site.baseurl}}/tools/index/#compatibility-matrices) to see if any of your tools will also need to be upgraded. +If your OpenSearch cluster interacts with other services in your environment, like Logstash or Beats, then you should check the [OpenSearch tools compatibility matrices]({{site.url}}{{site.baseurl}}/tools/index/#compatibility-matrices) to see if other components will need to be upgraded. ### Check plugin compatibility -Review the plugins you use to determine whether or not they are compatible with the target version of OpenSearch. Many of the official plugins can be found in the official [OpenSearch Project](https://github.com/opensearch-project) repository on GitHub. If you use any unofficial or third party plugins, then you should check the documentation for those plugins to determine if they will be compatible. +Review the plugins you use to determine compatibility with the target version of OpenSearch. Official OpenSearch Project plugins can be found in the official [OpenSearch Project](https://github.com/opensearch-project) repository on GitHub. If you use any third party plugins, then you should check the documentation for those plugins to determine if they are compatible. ### Back up configuration files From c63df498b1ce7327345c91e2dd6e8c9cba9be6c9 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Thu, 9 Feb 2023 11:24:21 -0800 Subject: [PATCH 27/54] Added banner about the status of the docs but pending review from Himanshu and Brian P Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/index.md | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index f2484fda7d..81df2dad81 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -17,6 +17,13 @@ Index compatibility is determined by the version of [Apache Lucene](https://luce If your upgrade path spans more than a single major version, and you want to retain any existing index(es), then you can use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. One alternative to reindexing is to reingest data from the origin, such as by replaying a datastream or ingesting data from a database. +## A note about this document + +--PENDING REVIEW FROM PRODUCT-- +We recognize that users are excited about upgrading OpenSearch, and eager to enjoy the latest features and improvements that have been added. Empowering users to upgrade existing clusters and migrate workflows from other solutions to OpenSearch is our goal, and we will continue to expand on these upgrade documents to cover additional topics, such as upgrading OpenSearch Dashboards, migrating your Kibana instance(s) to OpenSearch Dashboards, and preserving plugin configurations. + +If there's a specific process you would like to see added, please [submit an issue](https://github.com/opensearch-project/documentation-website/issues) on GitHub. + ## Workflow considerations Take time to plan the process before making any changes to your cluster. For example, consider how long the upgrade process will take. If your cluster is being used in production, how impactful is downtime? Do you have infrastructure in-place to stand up the new cluster in a testing or development environment before you move it into production, or do you need to upgrade the production hosts directly? The answers to questions like these will help you determine which upgrade path will work best in your environment. At a minimum, you should: @@ -44,27 +51,29 @@ Review the plugins you use to determine compatibility with the target version of ### Back up configuration files -Mitigate the risk of data loss by backing up any important files before you start an upgrade. Generally speaking, these files will be located in `opensearch/config` (OpenSearch) and `opensearch-dashboards/config` (OpenSearch Dashboards). Some examples include `opensearch.yml`, `opensearch_dashboards.yml`, security plugin backups, and TLS certificates. Once you identify which files you need to back up, copy them to remote storage so they can be restored, if necessary. +Mitigate the risk of data loss by backing up any important files before you start an upgrade. Generally speaking, these files will be located in `opensearch/config` (OpenSearch) and `opensearch-dashboards/config` (OpenSearch Dashboards). Some examples include `opensearch.yml`, `opensearch_dashboards.yml`, security plugin backups, and TLS certificates. Once you identify which files you need to back up, copy them to remote storage for safety. ### Create a snapshot -We recommend that you back up your cluster state and indexes using [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/). If the security plugin is enabled then you will need to take a additional steps, because the `.opendistro_security` index can't be directly restored. See [A word of caution]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/#a-word-of-caution) for details about backing up and restoring your security settings. +We recommend that you back up your cluster state and indexes using [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/). If you use the security plugin, make sure to read [A word of caution]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/#a-word-of-caution) for details about backing up and restoring your security settings. ## Upgrade methods Choose an appropriate method for upgrading your cluster to a new version of OpenSearch based on your requirements. -- [Rolling upgrade](#rolling-upgrade) allows you to upgrade nodes individually without stopping the cluster. -- [Cluster restart upgrade](#cluster-restart-upgrade) allows the upgrade to be performed while the cluster is stopped. +- [Rolling upgrade](#rolling-upgrade) allows you to upgrade nodes one at a time without stopping the cluster. +- [Cluster restart upgrade](#cluster-restart-upgrade) is the process of upgrading while the cluster is stopped. -Upgrades spanning more than a single major version of OpenSearch will require additional effort due to the need for reindexing. You should upgrade in steps, one major version at a time. After each upgrade you should reindex because OpenSearch is not compatible with indexes that are more than a single major version behind your cluster's OpenSearch/Lucene version. For more information, refer to the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API. +Upgrades spanning more than a single major version of OpenSearch will require additional effort due to the need for reindexing. For more information, refer to the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API. ### Rolling upgrade -Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Shard replication is stopped temporarily, then nodes are upgraded one at a time. A variation of the rolling upgrade, often referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. +Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Users can continue using OpenSearch throughout the process, and data can continue to be ingested. A variation of the rolling upgrade, often referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. OpenSearch nodes cannot join a cluster if the cluster manager is running a newer version of OpenSearch than the node requesting membership. To avoid this issue, you upgrade cluster manager-eligible nodes last. +See [Rolling Upgrade]({{site.url}}{{site.baseurl}}/upgrade-opensearch/rolling-upgrade/) for details about the process. + ### Cluster restart upgrade OpenSearch administrators might choose a restart upgrade if they aren't comfortable performing maintenance on a running cluster, if the cluster is being migrated to different infrastructure, or if they manage their cluster with [Docker Compose](https://github.com/docker/compose). During a rolling upgrade, only a single node is offline at any point in time. The cluster restart upgrade, however, involves stopping all nodes in the cluster, performing the upgrade, and starting the cluster back up. From 35ca70cbb35584f4c29273fcb7b9704a48b586d4 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Thu, 9 Feb 2023 13:46:16 -0800 Subject: [PATCH 28/54] Refined wording for note about this document Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 81df2dad81..10a2ec658c 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -19,10 +19,9 @@ If your upgrade path spans more than a single major version, and you want to ret ## A note about this document ---PENDING REVIEW FROM PRODUCT-- -We recognize that users are excited about upgrading OpenSearch, and eager to enjoy the latest features and improvements that have been added. Empowering users to upgrade existing clusters and migrate workflows from other solutions to OpenSearch is our goal, and we will continue to expand on these upgrade documents to cover additional topics, such as upgrading OpenSearch Dashboards, migrating your Kibana instance(s) to OpenSearch Dashboards, and preserving plugin configurations. +We recognize that users are excited about upgrading OpenSearch and eager to enjoy the latest features and improvements that have been added. We will continue to expand on these upgrade and migration documents to cover [additional topics](link to meta issue), such as upgrading OpenSearch Dashboards, migrating your Kibana instance(s) to OpenSearch Dashboards, and preserving custom configurations, such as for the security plugin. -If there's a specific process you would like to see added, please [submit an issue](https://github.com/opensearch-project/documentation-website/issues) on GitHub. +If would like to see a specific process added, or would like to contribute yourself, please [submit an issue](https://github.com/opensearch-project/documentation-website/issues) on GitHub. Check out the [Contributor Guidelines](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md) to see how you can help! ## Workflow considerations @@ -68,7 +67,7 @@ Upgrades spanning more than a single major version of OpenSearch will require ad ### Rolling upgrade -Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Users can continue using OpenSearch throughout the process, and data can continue to be ingested. A variation of the rolling upgrade, often referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. +Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Users can continue using OpenSearch throughout the process, and data can continue to be ingested. A variation of the rolling upgrade, referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. OpenSearch nodes cannot join a cluster if the cluster manager is running a newer version of OpenSearch than the node requesting membership. To avoid this issue, you upgrade cluster manager-eligible nodes last. From 33c44339d5bf18ed3c776aa48824f85b8342499c Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Thu, 9 Feb 2023 13:48:54 -0800 Subject: [PATCH 29/54] Added note to restart upgrade Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 10a2ec658c..1fd8e14161 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -75,7 +75,9 @@ See [Rolling Upgrade]({{site.url}}{{site.baseurl}}/upgrade-opensearch/rolling-up ### Cluster restart upgrade -OpenSearch administrators might choose a restart upgrade if they aren't comfortable performing maintenance on a running cluster, if the cluster is being migrated to different infrastructure, or if they manage their cluster with [Docker Compose](https://github.com/docker/compose). During a rolling upgrade, only a single node is offline at any point in time. The cluster restart upgrade, however, involves stopping all nodes in the cluster, performing the upgrade, and starting the cluster back up. +OpenSearch administrators might choose a restart upgrade if they aren't comfortable performing maintenance on a running cluster, if the cluster is being migrated to different infrastructure, or if they manage their cluster with [Docker Compose](https://github.com/docker/compose). During a rolling upgrade, only a single node is offline at any time. + +Conversely, a cluster restart upgrade requires you to stop OpenSearch on all nodes in the cluster and upgrade OpenSearch on each node. After all of the nodes are upgraded, OpenSearch is started and the cluster bootstraps to the new version. ## Compatibility From 7c28c0b3959b4278ba9dafb46c54782f2d6a6d22 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Fri, 10 Feb 2023 05:54:35 -0800 Subject: [PATCH 30/54] Stashing changes before weekend Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/index.md | 21 +++++++++---------- .../upgrade-opensearch/rolling-upgrade.md | 9 +++++++- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 1fd8e14161..4e143b2bb8 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -11,17 +11,12 @@ redirect_from: The OpenSearch Project releases regular updates that include new features, enhancements, and bug fixes. OpenSearch uses [Semantic Versioning](https://semver.org/), which means that breaking changes are only introduced between major version releases. To learn about upcoming features and fixes, review the [OpenSearch Project Roadmap](https://github.com/orgs/opensearch-project/projects/1) on GitHub. To see a list of previous releases, or to learn more about how OpenSearch uses versioning, check out the [Release Schedule and Maintenance Policy]({{site.url}}/releases.html). -OpenSearch nodes are compatible with nodes running any other minor version within the same major version release. For example, 1.1.0 is compatible with 1.3.7 because they are part of the same major version (1.x). Additionally, OpenSearch nodes and indexes are backwards-compatible with the previous major version (**N-1**). That means, for example, that an index created by an OpenSearch node running version 1.3.7 could be restored from a snapshot to an OpenSearch cluster running version 2.5.0. There are special considerations that should be taken into consideration if system indexes are also being restored. These considerations will be added as we continue to improve and expand this documentation. - -Index compatibility is determined by the version of [Apache Lucene](https://lucene.apache.org/) that created the index. If an index was created by an OpenSearch cluster running version 1.0.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. See the [Lucene version reference](#lucene-version-reference) table for Lucene versions running in OpenSearch 1.0.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. - -If your upgrade path spans more than a single major version, and you want to retain any existing index(es), then you can use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. One alternative to reindexing is to reingest data from the origin, such as by replaying a datastream or ingesting data from a database. - ## A note about this document -We recognize that users are excited about upgrading OpenSearch and eager to enjoy the latest features and improvements that have been added. We will continue to expand on these upgrade and migration documents to cover [additional topics](link to meta issue), such as upgrading OpenSearch Dashboards, migrating your Kibana instance(s) to OpenSearch Dashboards, and preserving custom configurations, such as for the security plugin. +We recognize that users are excited about upgrading OpenSearch and eager to enjoy the latest features and improvements that have been added. We will continue to expand on these upgrade and migration documents to cover [additional topics](link to meta issue), such as upgrading OpenSearch Dashboards and preserving custom configurations, such as for plugins. If would like to see a specific process added, or would like to contribute yourself, please [submit an issue](https://github.com/opensearch-project/documentation-website/issues) on GitHub. Check out the [Contributor Guidelines](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md) to see how you can help! +{: .tip} ## Workflow considerations @@ -33,9 +28,6 @@ Take time to plan the process before making any changes to your cluster. For exa - [Back up configuration files](#back-up-configuration-files) - [Create a snapshot](#create-a-snapshot) -Stop any non-essential indexing before you begin the upgrade procedure. -{: .tip} - ### Review breaking changes It's important to determine how the new version of OpenSearch will fit into your production environment. Review [Breaking changes]({{site.url}}{{site.baseurl}}/breaking-changes/) before beginning any upgrade procedures to determine if you will need to make adjustments in your workflow. For example, upstream or downstream components might need to be adjusted due to an API change. @@ -73,6 +65,9 @@ OpenSearch nodes cannot join a cluster if the cluster manager is running a newer See [Rolling Upgrade]({{site.url}}{{site.baseurl}}/upgrade-opensearch/rolling-upgrade/) for details about the process. +Stop any non-essential indexing before you begin the upgrade procedure to eliminate unnecessary resource strains on the cluster while you perform the upgrade. +{: .tip} + ### Cluster restart upgrade OpenSearch administrators might choose a restart upgrade if they aren't comfortable performing maintenance on a running cluster, if the cluster is being migrated to different infrastructure, or if they manage their cluster with [Docker Compose](https://github.com/docker/compose). During a rolling upgrade, only a single node is offline at any time. @@ -81,7 +76,11 @@ Conversely, a cluster restart upgrade requires you to stop OpenSearch on all nod ## Compatibility -ADD TO ME! Here I'll add some commentary about what version compatibility considerations can be taken into account. Maybe another table or external link references would be good. +OpenSearch nodes are compatible with nodes running any other minor version within the same major version release. For example, 1.1.0 is compatible with 1.3.7 because they are part of the same major version (1.x). Additionally, OpenSearch nodes and indexes are backwards-compatible with the previous major version (**N-1**). That means, for example, that an index created by an OpenSearch node running version 1.3.7 could be restored from a snapshot to an OpenSearch cluster running version 2.5.0. There are special considerations that should be taken into consideration if system indexes are also being restored. These considerations will be added as we continue to improve and expand this documentation. + +Index compatibility is determined by the version of [Apache Lucene](https://lucene.apache.org/) that created the index. If an index was created by an OpenSearch cluster running version 1.0.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. See the [Lucene version reference](#lucene-version-reference) table for Lucene versions running in OpenSearch 1.0.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. + +If your upgrade path spans more than a single major version, and you want to retain any existing index(es), then you can use the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API to make your indexes compatible with the target version of OpenSearch before upgrading. For example, if your cluster is currently running Elasticsearch 6.8 and you want to upgrade to OpenSearch 2.x, then you must first upgrade to OpenSearch 1.x, recreate your indexes using the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API, and finally upgrade to 2.x. One alternative to reindexing is to reingest data from the origin, such as by replaying a datastream or ingesting data from a database. ### Lucene version reference diff --git a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md index 113fd163fb..8b84c2e502 100644 --- a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md @@ -162,7 +162,7 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y os-node-01 7.10.2 dimr - os-node-03 7.10.2 dimr - ``` - In the sample output, the new OpenSearch node reports a running version of `7.10.2` to the cluster for compatibility purposes. You can manually confirm the version by reviewing the output of the `/_nodes` API endpoint, like the following command. Replace `` with the name of your node. See [Nodes API]({{site.url}}{{site.baseurl}}/latest/api-reference/nodes-apis/index/) to learn more. + In the sample output, the new OpenSearch node reports a running version of `7.10.2` to the cluster. This is the result of `compatibility.override_main_response_version`, which is used when connecting to a cluster with legacy clients that check for a version. You can manually confirm the version of the node by calling the `/_nodes` API endpoint, like the following command. Replace `` with the name of your node. See [Nodes API]({{site.url}}{{site.baseurl}}/latest/api-reference/nodes-apis/index/) to learn more. ``` curl -s -X GET 'localhost:9201/_nodes/?pretty=true' | jq -r '.nodes | .[] | "\(.name) v\(.version)"' ``` @@ -229,3 +229,10 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y "active_shards_percent_as_number" : 100.0 } ``` +1. That's it! The upgrade is complete and your users can start using the latest features right away. + +### Relate links + +- []() +- []() +- []() From cc7e0025266e3f551d24445f40e028c7ebfbe5cc Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Mon, 13 Feb 2023 08:45:28 -0800 Subject: [PATCH 31/54] Created clean meta issue for fresh pushes and added link Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 4e143b2bb8..d353f0123f 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -13,7 +13,7 @@ The OpenSearch Project releases regular updates that include new features, enhan ## A note about this document -We recognize that users are excited about upgrading OpenSearch and eager to enjoy the latest features and improvements that have been added. We will continue to expand on these upgrade and migration documents to cover [additional topics](link to meta issue), such as upgrading OpenSearch Dashboards and preserving custom configurations, such as for plugins. +We recognize that users are excited about upgrading OpenSearch to enjoy the latest features, and we will continue to expand on these upgrade and migration documents to cover additional topics, such as upgrading OpenSearch Dashboards and preserving custom configurations, such as for plugins. To see what's coming next, or to make a request for future content, leave a comment on the [upgrade and migration documentation meta issue](https://github.com/opensearch-project/documentation-website/issues/2830) in the [OpenSearch Project](https://github.com/opensearch-project) on GitHub. If would like to see a specific process added, or would like to contribute yourself, please [submit an issue](https://github.com/opensearch-project/documentation-website/issues) on GitHub. Check out the [Contributor Guidelines](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md) to see how you can help! {: .tip} From aeec5b19241cd35c43d07c77eda59fecb5fc068d Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Mon, 13 Feb 2023 08:47:29 -0800 Subject: [PATCH 32/54] Added related links Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/rolling-upgrade.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md index 8b84c2e502..87fadb87ec 100644 --- a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md @@ -231,8 +231,9 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y ``` 1. That's it! The upgrade is complete and your users can start using the latest features right away. -### Relate links +### Related links -- []() -- []() -- []() +- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) +- [Performance analyzer]({{site.url}}{{site.baseurl}}/monitoring-plugins/pa/index/) +- [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/index/) +- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/) From fd4d018684db43bc6f803f4b22343673264943ab Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Mon, 13 Feb 2023 09:42:33 -0800 Subject: [PATCH 33/54] Editing Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 2 -- _install-and-configure/upgrade-opensearch/rolling-upgrade.md | 4 ++-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index d353f0123f..6986b78d15 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -11,8 +11,6 @@ redirect_from: The OpenSearch Project releases regular updates that include new features, enhancements, and bug fixes. OpenSearch uses [Semantic Versioning](https://semver.org/), which means that breaking changes are only introduced between major version releases. To learn about upcoming features and fixes, review the [OpenSearch Project Roadmap](https://github.com/orgs/opensearch-project/projects/1) on GitHub. To see a list of previous releases, or to learn more about how OpenSearch uses versioning, check out the [Release Schedule and Maintenance Policy]({{site.url}}/releases.html). -## A note about this document - We recognize that users are excited about upgrading OpenSearch to enjoy the latest features, and we will continue to expand on these upgrade and migration documents to cover additional topics, such as upgrading OpenSearch Dashboards and preserving custom configurations, such as for plugins. To see what's coming next, or to make a request for future content, leave a comment on the [upgrade and migration documentation meta issue](https://github.com/opensearch-project/documentation-website/issues/2830) in the [OpenSearch Project](https://github.com/opensearch-project) on GitHub. If would like to see a specific process added, or would like to contribute yourself, please [submit an issue](https://github.com/opensearch-project/documentation-website/issues) on GitHub. Check out the [Contributor Guidelines](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md) to see how you can help! diff --git a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md index 87fadb87ec..6bb9f9a499 100644 --- a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md @@ -7,14 +7,14 @@ nav_order: 10 # Rolling Upgrade -Rolling upgrades, sometimes referred to as "node replacement upgrades," can be performed on running clusters with virtually no downtime. Nodes are dismissed from the cluster and replaced one at a time by nodes running the target version. During this process you can continue to index and query data in your cluster. +Rolling upgrades, sometimes referred to as "node replacement upgrades," can be performed on running clusters with virtually no downtime. Nodes are individually stopped and upgraded in place. Alternatively, nodes can be stopped and replaced, one at a time, by hosts running the new version. During this process you can continue to index and query data in your cluster. This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. {:.note} ### About this guide -The sample outputs and API responses included in this document were generated in a development environment. Testing and validation was performed by upgrading an Elasticsearch 7.10.2 cluster of 4 nodes to OpenSearch 1.3.7. However, this process can be applied to any **N → N+1** version upgrade of OpenSearch. +The sample outputs and API responses included in this document were generated in a development environment. Testing and validation was performed by upgrading an Elasticsearch 7.10.2 cluster of 4 nodes to OpenSearch 1.3.7 in a Docker environment. However, this process can be applied to any **N→N+1** version upgrade of OpenSearch. ### Prepare to upgrade From 8d16b296136afa83da440b9d6d6c5d7b1ba1466e Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Mon, 13 Feb 2023 11:50:47 -0800 Subject: [PATCH 34/54] Editing continued Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/index.md | 45 +++++++++++-------- .../upgrade-opensearch/rolling-upgrade.md | 13 +++--- 2 files changed, 32 insertions(+), 26 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 6986b78d15..bab82c15e4 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -18,31 +18,41 @@ If would like to see a specific process added, or would like to contribute yours ## Workflow considerations -Take time to plan the process before making any changes to your cluster. For example, consider how long the upgrade process will take. If your cluster is being used in production, how impactful is downtime? Do you have infrastructure in-place to stand up the new cluster in a testing or development environment before you move it into production, or do you need to upgrade the production hosts directly? The answers to questions like these will help you determine which upgrade path will work best in your environment. At a minimum, you should: +Take time to plan the process before making any changes to your cluster. For example, consider how long the upgrade process will take. If your cluster is being used in production, how impactful is downtime? Do you have infrastructure in place to stand up the new cluster in a testing or development environment before you move it into production, or do you need to upgrade the production hosts directly? The answers to questions like these will help you determine which upgrade path will work best in your environment. + +At a minimum, you should: - [Review breaking changes](#review-breaking-changes) - [Review the OpenSearch tools compatibility matrices](#review-the-opensearch-tools-compatibility-matrices) -- [Check plugin compatibility](#check-plugin-compatibility) +- [Check plugin compatibility](#review-plugin-compatibility) - [Back up configuration files](#back-up-configuration-files) -- [Create a snapshot](#create-a-snapshot) +- [Take a snapshot](#take-a-snapshot) + +Stop any non-essential indexing before you begin the upgrade procedure to eliminate unnecessary resource strains on the cluster while you perform the upgrade. +{: .tip} ### Review breaking changes -It's important to determine how the new version of OpenSearch will fit into your production environment. Review [Breaking changes]({{site.url}}{{site.baseurl}}/breaking-changes/) before beginning any upgrade procedures to determine if you will need to make adjustments in your workflow. For example, upstream or downstream components might need to be adjusted due to an API change. +It's important to determine how the new version of OpenSearch will fit into your environment. Review [Breaking changes]({{site.url}}{{site.baseurl}}/breaking-changes/) before beginning any upgrade procedures to determine if you will need to make adjustments in your workflow. For example, upstream or downstream components might need to be modified to be compatible with an API change when you upgrade to a new major version of OpenSearch. ### Review the OpenSearch tools compatibility matrices If your OpenSearch cluster interacts with other services in your environment, like Logstash or Beats, then you should check the [OpenSearch tools compatibility matrices]({{site.url}}{{site.baseurl}}/tools/index/#compatibility-matrices) to see if other components will need to be upgraded. -### Check plugin compatibility +### Review plugin compatibility -Review the plugins you use to determine compatibility with the target version of OpenSearch. Official OpenSearch Project plugins can be found in the official [OpenSearch Project](https://github.com/opensearch-project) repository on GitHub. If you use any third party plugins, then you should check the documentation for those plugins to determine if they are compatible. +Review the plugins you use to determine compatibility with the target version of OpenSearch. Official OpenSearch Project plugins can be found in the [OpenSearch Project](https://github.com/opensearch-project) repository on GitHub. If you use any third party plugins, then you should check the documentation for those plugins to determine if they are compatible. ### Back up configuration files -Mitigate the risk of data loss by backing up any important files before you start an upgrade. Generally speaking, these files will be located in `opensearch/config` (OpenSearch) and `opensearch-dashboards/config` (OpenSearch Dashboards). Some examples include `opensearch.yml`, `opensearch_dashboards.yml`, security plugin backups, and TLS certificates. Once you identify which files you need to back up, copy them to remote storage for safety. +Mitigate the risk of data loss by backing up any important files before you start an upgrade. Generally speaking, these files will be located in either of two directories: + +- `opensearch/config` +- `opensearch-dashboards/config` -### Create a snapshot +Some examples include `opensearch.yml`, `opensearch_dashboards.yml`, plugin configuration files, and TLS certificates. Once you identify which files you want to back up, copy them to remote storage for safety. + +### Take a snapshot We recommend that you back up your cluster state and indexes using [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/). If you use the security plugin, make sure to read [A word of caution]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/#a-word-of-caution) for details about backing up and restoring your security settings. @@ -50,31 +60,28 @@ We recommend that you back up your cluster state and indexes using [Snapshots]({ Choose an appropriate method for upgrading your cluster to a new version of OpenSearch based on your requirements. -- [Rolling upgrade](#rolling-upgrade) allows you to upgrade nodes one at a time without stopping the cluster. -- [Cluster restart upgrade](#cluster-restart-upgrade) is the process of upgrading while the cluster is stopped. +- [Rolling upgrade](#rolling-upgrade) is upgrading nodes one at a time without stopping the cluster. +- [Cluster restart upgrade](#cluster-restart-upgrade) is the process of upgrading services while the cluster is stopped. -Upgrades spanning more than a single major version of OpenSearch will require additional effort due to the need for reindexing. For more information, refer to the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API. +Upgrades spanning more than a single major version of OpenSearch will require additional effort due to the need for reindexing. For more information, refer to the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API. See the [Lucene version reference](#lucene-version-reference) table included later in this guide for help planning your data migration. ### Rolling upgrade -Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Users can continue using OpenSearch throughout the process, and data can continue to be ingested. A variation of the rolling upgrade, referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. +Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Data may continue to be ingested, analyzed or queried throughout the process. A variation of the rolling upgrade, referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. OpenSearch nodes cannot join a cluster if the cluster manager is running a newer version of OpenSearch than the node requesting membership. To avoid this issue, you upgrade cluster manager-eligible nodes last. -See [Rolling Upgrade]({{site.url}}{{site.baseurl}}/upgrade-opensearch/rolling-upgrade/) for details about the process. - -Stop any non-essential indexing before you begin the upgrade procedure to eliminate unnecessary resource strains on the cluster while you perform the upgrade. -{: .tip} +See [Rolling Upgrade]({{site.url}}{{site.baseurl}}/install-and-configure/upgrade-opensearch/rolling-upgrade/) for details about the process. ### Cluster restart upgrade -OpenSearch administrators might choose a restart upgrade if they aren't comfortable performing maintenance on a running cluster, if the cluster is being migrated to different infrastructure, or if they manage their cluster with [Docker Compose](https://github.com/docker/compose). During a rolling upgrade, only a single node is offline at any time. +OpenSearch administrators might choose to perform a cluster restart upgrade if they aren't comfortable performing maintenance on a running cluster, if the cluster is being migrated to different infrastructure, or if they manage their cluster with [Docker Compose](https://github.com/docker/compose). -Conversely, a cluster restart upgrade requires you to stop OpenSearch on all nodes in the cluster and upgrade OpenSearch on each node. After all of the nodes are upgraded, OpenSearch is started and the cluster bootstraps to the new version. +Unlike a rolling upgrade, where only one node is offline at a time, a cluster restart upgrade requires you to stop OpenSearch and OpenSearch Dashboards on all nodes in the cluster before proceeding. After the nodes are stopped, a new version of OpenSearch is installed. Then, OpenSearch is started and the cluster bootstraps to the new version. ## Compatibility -OpenSearch nodes are compatible with nodes running any other minor version within the same major version release. For example, 1.1.0 is compatible with 1.3.7 because they are part of the same major version (1.x). Additionally, OpenSearch nodes and indexes are backwards-compatible with the previous major version (**N-1**). That means, for example, that an index created by an OpenSearch node running version 1.3.7 could be restored from a snapshot to an OpenSearch cluster running version 2.5.0. There are special considerations that should be taken into consideration if system indexes are also being restored. These considerations will be added as we continue to improve and expand this documentation. +OpenSearch nodes are compatible with other OpenSearch nodes running any other minor version within the same major version release. For example, 1.1.0 is compatible with 1.3.7 because they are part of the same major version (1.x). Additionally, OpenSearch nodes and indexes are backwards-compatible with the previous major version. That means, for example, that an index created by an OpenSearch node running any 1.x version could be restored from a snapshot to an OpenSearch cluster running any 2.x version. Index compatibility is determined by the version of [Apache Lucene](https://lucene.apache.org/) that created the index. If an index was created by an OpenSearch cluster running version 1.0.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. See the [Lucene version reference](#lucene-version-reference) table for Lucene versions running in OpenSearch 1.0.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. diff --git a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md index 6bb9f9a499..c5af021555 100644 --- a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md @@ -12,18 +12,17 @@ Rolling upgrades, sometimes referred to as "node replacement upgrades," can be p This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. {:.note} -### About this guide - -The sample outputs and API responses included in this document were generated in a development environment. Testing and validation was performed by upgrading an Elasticsearch 7.10.2 cluster of 4 nodes to OpenSearch 1.3.7 in a Docker environment. However, this process can be applied to any **N→N+1** version upgrade of OpenSearch. +The sample outputs and API responses included in this document were generated in a development environment using Docker containers. Validation was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7; however, this process can be applied to any **N→N+1** version upgrade of OpenSearch on any platform. Certain commands, such as listing running containers in Docker, are included as an aid to the reader but the specific commands used on your host(s) will be different depending on your distribution and host operating system. +{: .note} -### Prepare to upgrade +## Prepare to upgrade Review [Upgrading OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-opensearch/index/) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. -OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. +**Important:** OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. {: .note} -### Rolling upgrade +## Rolling upgrade 1. Verify the health of your OpenSearch cluster before you begin. You should resolve any index or shard allocation issues prior to upgrading to ensure that your data is preserved. A status of **green** indicates that all primary and replica shards are allocated. See [Cluster health]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-health/) for more information. ```bash @@ -162,7 +161,7 @@ OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then y os-node-01 7.10.2 dimr - os-node-03 7.10.2 dimr - ``` - In the sample output, the new OpenSearch node reports a running version of `7.10.2` to the cluster. This is the result of `compatibility.override_main_response_version`, which is used when connecting to a cluster with legacy clients that check for a version. You can manually confirm the version of the node by calling the `/_nodes` API endpoint, like the following command. Replace `` with the name of your node. See [Nodes API]({{site.url}}{{site.baseurl}}/latest/api-reference/nodes-apis/index/) to learn more. + In the sample output, the new OpenSearch node reports a running version of `7.10.2` to the cluster. This is the result of `compatibility.override_main_response_version`, which is used when connecting to a cluster with legacy clients that check for a version. You can manually confirm the version of the node by calling the `/_nodes` API endpoint, like the following command. Replace `` with the name of your node. See [Nodes API]({{site.url}}{{site.baseurl}}/api-reference/nodes-apis/index/) to learn more. ``` curl -s -X GET 'localhost:9201/_nodes/?pretty=true' | jq -r '.nodes | .[] | "\(.name) v\(.version)"' ``` From f560c6bd3547cfc3ed4958985c26223bf97f26bb Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Mon, 13 Feb 2023 12:44:05 -0800 Subject: [PATCH 35/54] Working on the table dimensions Signed-off-by: JeffH-AWS --- _install-and-configure/upgrade-opensearch/index.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index bab82c15e4..b5c8c34c20 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -67,7 +67,7 @@ Upgrades spanning more than a single major version of OpenSearch will require ad ### Rolling upgrade -Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Data may continue to be ingested, analyzed or queried throughout the process. A variation of the rolling upgrade, referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. +Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Data may continue to be ingested, analyzed and queried as nodes are invididually stopped, upgraded, and restarted. A variation of the rolling upgrade, referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. You might perform node replacement if you are upgrading the underlying host(s) as well. OpenSearch nodes cannot join a cluster if the cluster manager is running a newer version of OpenSearch than the node requesting membership. To avoid this issue, you upgrade cluster manager-eligible nodes last. @@ -75,13 +75,13 @@ See [Rolling Upgrade]({{site.url}}{{site.baseurl}}/install-and-configure/upgrade ### Cluster restart upgrade -OpenSearch administrators might choose to perform a cluster restart upgrade if they aren't comfortable performing maintenance on a running cluster, if the cluster is being migrated to different infrastructure, or if they manage their cluster with [Docker Compose](https://github.com/docker/compose). +OpenSearch administrators might choose to perform a cluster restart upgrade for several reasons. For example, if the administrator doesn't want to perform maintenance on a running cluster, or if the cluster is being migrated to different infrastructure. Unlike a rolling upgrade, where only one node is offline at a time, a cluster restart upgrade requires you to stop OpenSearch and OpenSearch Dashboards on all nodes in the cluster before proceeding. After the nodes are stopped, a new version of OpenSearch is installed. Then, OpenSearch is started and the cluster bootstraps to the new version. ## Compatibility -OpenSearch nodes are compatible with other OpenSearch nodes running any other minor version within the same major version release. For example, 1.1.0 is compatible with 1.3.7 because they are part of the same major version (1.x). Additionally, OpenSearch nodes and indexes are backwards-compatible with the previous major version. That means, for example, that an index created by an OpenSearch node running any 1.x version could be restored from a snapshot to an OpenSearch cluster running any 2.x version. +OpenSearch nodes are compatible with other OpenSearch nodes running any other *minor* version within the same *major* version release. For example, 1.1.0 is compatible with 1.3.7 because they are part of the same *major* version (1.x). Additionally, OpenSearch nodes and indexes are backwards-compatible with the previous major version. That means, for example, that an index created by an OpenSearch node running any 1.x version could be restored from a snapshot to an OpenSearch cluster running any 2.x version. Index compatibility is determined by the version of [Apache Lucene](https://lucene.apache.org/) that created the index. If an index was created by an OpenSearch cluster running version 1.0.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. See the [Lucene version reference](#lucene-version-reference) table for Lucene versions running in OpenSearch 1.0.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. @@ -93,7 +93,9 @@ If you plan to retain old indexes after the OpenSearch version upgrade, then you @@ -120,11 +122,11 @@ td { 9.4.1 2.4.0 - - + — 9.4.0 - - + — 8.5 @@ -144,12 +146,12 @@ td { 9.0.0 - - + — 8.1
8.0 8.11.1 - - + — 7.17 @@ -169,52 +171,53 @@ td { 8.8.0 - - + — 7.12 8.7.0 - - + — 7.11
7.10 8.6.2 - - + — 7.9 8.5.1 - - + — 7.8
7.7 8.4.0 - - + — 7.6 8.3.0 - - + — 7.5 8.2.0 - - + — 7.4 8.1.0 - - + — 7.3 8.0.0 - - - 7.2X7.1 + — + 7.2
7.1 7.7.3 - - + — 6.8 - \ No newline at end of file + +

A dash (—) indicates that there is no product version containing the specified version of Apache Lucene.

\ No newline at end of file diff --git a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md index c5af021555..8f4ccf1a16 100644 --- a/_install-and-configure/upgrade-opensearch/rolling-upgrade.md +++ b/_install-and-configure/upgrade-opensearch/rolling-upgrade.md @@ -9,12 +9,11 @@ nav_order: 10 Rolling upgrades, sometimes referred to as "node replacement upgrades," can be performed on running clusters with virtually no downtime. Nodes are individually stopped and upgraded in place. Alternatively, nodes can be stopped and replaced, one at a time, by hosts running the new version. During this process you can continue to index and query data in your cluster. +The sample outputs and API responses included in this document were generated in a development environment using Docker containers. Validation was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7; however, this process can be applied to any **N→N+1** version upgrade of OpenSearch on any platform. Certain commands, such as listing running containers in Docker, are included as an aid to the reader but the specific commands used on your host(s) will be different depending on your distribution and host operating system. + This guide assumes that you are comfortable working from the Linux command line interface (CLI). You should understand how to input commands, navigate between directories, and edit text files. For help with [Docker](https://www.docker.com/) or [Docker Compose](https://github.com/docker/compose), refer to the official documentation on their websites. {:.note} -The sample outputs and API responses included in this document were generated in a development environment using Docker containers. Validation was performed by upgrading an Elasticsearch 7.10.2 cluster to OpenSearch 1.3.7; however, this process can be applied to any **N→N+1** version upgrade of OpenSearch on any platform. Certain commands, such as listing running containers in Docker, are included as an aid to the reader but the specific commands used on your host(s) will be different depending on your distribution and host operating system. -{: .note} - ## Prepare to upgrade Review [Upgrading OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-opensearch/index/) for recommendations about backing up your configuration files and creating a snapshot of the cluster state and indexes before you make any changes to your OpenSearch cluster. @@ -22,7 +21,7 @@ Review [Upgrading OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-opensearch/in **Important:** OpenSearch nodes cannot be downgraded. If you need to revert the upgrade, then you will need to perform a fresh installation of OpenSearch and restore the cluster from a snapshot. Take a snapshot and store it in a remote repository before beginning the upgrade procedure. {: .note} -## Rolling upgrade +## Upgrade steps 1. Verify the health of your OpenSearch cluster before you begin. You should resolve any index or shard allocation issues prior to upgrading to ensure that your data is preserved. A status of **green** indicates that all primary and replica shards are allocated. See [Cluster health]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-health/) for more information. ```bash @@ -83,18 +82,7 @@ Review [Upgrading OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-opensearch/in } ``` 1. Review your cluster and identify the first node to upgrade. Eligible cluster manager nodes should be upgraded last because OpenSearch nodes can join a cluster with manager nodes running an older version, but they cannot join a cluster with all manager nodes running a newer version. - ```bash - docker container ls - ``` - Sample output: - ```bash - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - a50a9617991b docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9204->9200/tcp, :::9204->9200/tcp, 0.0.0.0:9604->9600/tcp, :::9604->9600/tcp os-node-04 - fac35167fcbd docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9203->9200/tcp, :::9203->9200/tcp, 0.0.0.0:9603->9600/tcp, :::9603->9600/tcp os-node-03 - fa4efbe64cbf docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9202->9200/tcp, :::9202->9200/tcp, 0.0.0.0:9602->9600/tcp, :::9602->9600/tcp os-node-02 - 17e898d67ac2 docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2 "/tini -- /usr/local…" 18 minutes ago Up 18 minutes 9300/tcp, 0.0.0.0:9201->9200/tcp, :::9201->9200/tcp, 0.0.0.0:9601->9600/tcp, :::9601->9600/tcp os-node-01 - ``` -1. Query `_cat/nodes` to verify which node has been elected as cluster manager. Note that OpenSearch 1.x versions use the heading "master," which has been deprecated and replaced by "cluster_manager" in OpenSearch 2.x and later. +1. Query the `_cat/nodes` endpoint to verify which node was promoted to cluster manager. Note that OpenSearch 1.x versions use the term "master," which has been deprecated and replaced by "cluster_manager" in OpenSearch 2.x and later. ```bash curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t ``` @@ -106,17 +94,7 @@ Review [Upgrading OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-opensearch/in os-node-03 7.10.2 dimr - os-node-02 7.10.2 dimr * ``` -1. Stop the node you are upgrading. - ```bash - docker stop && docker container rm - ``` - Sample output: - ```bash - $ docker stop os-node-01 && docker container rm os-node-01 - os-node-01 - os-node-01 - ``` - **Important:** Do not delete the volume associated with the container when you delete the container. The new OpenSearch container will use the existing volume. **Deleting the volume will result in data loss.** +1. Stop the node you are upgrading. Do not delete the volume associated with the container when you delete the container. The new OpenSearch container will use the existing volume. **Deleting the volume will result in data loss.** 1. Confirm that the associated node has been dismissed from the cluster. ```bash curl -s "http://localhost:9202/_cat/nodes?v&h=name,version,node.role,master" | column -t @@ -145,10 +123,6 @@ Review [Upgrading OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-opensearch/in --name os-node-01 \ opensearchproject/opensearch:1.3.7 ``` - Sample output: - ```bash - b6d06de7a016aa3bb76c133c55ba4e0e605f522c7a6a4ebd2aa6c6a6d3f49728 - ``` 1. Query the `_cat/nodes` endpoint after OpenSearch is running on the new node to confirm that it has joined the cluster. ```bash curl -s "http://localhost:9201/_cat/nodes?v&h=name,version,node.role,master" | column -t @@ -228,9 +202,9 @@ Review [Upgrading OpenSearch]({{site.url}}{{site.baseurl}}/upgrade-opensearch/in "active_shards_percent_as_number" : 100.0 } ``` -1. That's it! The upgrade is complete and your users can start using the latest features right away. +1. The upgrade is complete and you can begin enjoying the latest features and fixes! -### Related links +### Related articles - [OpenSearch configuration]({{site.url}}{{site.baseurl}}/install-and-configure/configuration/) - [Performance analyzer]({{site.url}}{{site.baseurl}}/monitoring-plugins/pa/index/) From 4feb891a252ac08ff1347b042bc698d0b106d576 Mon Sep 17 00:00:00 2001 From: JeffH-AWS Date: Tue, 14 Feb 2023 07:43:42 -0800 Subject: [PATCH 37/54] Doc review changes Signed-off-by: JeffH-AWS --- .../upgrade-opensearch/index.md | 32 +++++++++++-------- .../upgrade-opensearch/rolling-upgrade.md | 28 ++++------------ 2 files changed, 25 insertions(+), 35 deletions(-) diff --git a/_install-and-configure/upgrade-opensearch/index.md b/_install-and-configure/upgrade-opensearch/index.md index 6c7ceea76a..a992e513fd 100644 --- a/_install-and-configure/upgrade-opensearch/index.md +++ b/_install-and-configure/upgrade-opensearch/index.md @@ -7,18 +7,24 @@ redirect_from: - /upgrade-opensearch/index/ --- -# Upgrade OpenSearch +# Upgrading OpenSearch -The OpenSearch Project releases regular updates that include new features, enhancements, and bug fixes. OpenSearch uses [Semantic Versioning](https://semver.org/), which means that breaking changes are only introduced between major version releases. To learn about upcoming features and fixes, review the [OpenSearch Project Roadmap](https://github.com/orgs/opensearch-project/projects/1) on GitHub. To see a list of previous releases, or to learn more about how OpenSearch uses versioning, check out the [Release Schedule and Maintenance Policy]({{site.url}}/releases.html). +The OpenSearch Project releases regular updates that include new features, enhancements, and bug fixes. OpenSearch uses [Semantic Versioning](https://semver.org/), which means that breaking changes are only introduced between major version releases. To learn about upcoming features and fixes, review the [OpenSearch Project Roadmap](https://github.com/orgs/opensearch-project/projects/1) on GitHub. To see a list of previous releases, or to learn more about how OpenSearch uses versioning, go to [Release Schedule and Maintenance Policy]({{site.url}}/releases.html). We recognize that users are excited about upgrading OpenSearch to enjoy the latest features, and we will continue to expand on these upgrade and migration documents to cover additional topics, such as upgrading OpenSearch Dashboards and preserving custom configurations, such as for plugins. To see what's coming next, or to make a request for future content, leave a comment on the [upgrade and migration documentation meta issue](https://github.com/opensearch-project/documentation-website/issues/2830) in the [OpenSearch Project](https://github.com/opensearch-project) on GitHub. -If would like to see a specific process added, or would like to contribute yourself, please [submit an issue](https://github.com/opensearch-project/documentation-website/issues) on GitHub. Check out the [Contributor Guidelines](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md) to see how you can help! +If would like to see a specific process added, or would like to contribute yourself, please [submit an issue](https://github.com/opensearch-project/documentation-website/issues) on GitHub. Check out the [Contributor Guidelines](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md) to see how you can help. {: .tip} ## Workflow considerations -Take time to plan the process before making any changes to your cluster. For example, consider how long the upgrade process will take. If your cluster is being used in production, how impactful is downtime? Do you have infrastructure in place to stand up the new cluster in a testing or development environment before you move it into production, or do you need to upgrade the production hosts directly? The answers to questions like these will help you determine which upgrade path will work best in your environment. +Take time to plan the process before making any changes to your cluster. For example, consider the following questions: + +- How long the upgrade process will take? +- If your cluster is being used in production, how impactful is downtime? +- Do you have infrastructure in place to stand up the new cluster in a testing or development environment before you move it into production, or do you need to upgrade the production hosts directly? + +The answers to questions like these will help you determine which upgrade path will work best in your environment. At a minimum, you should: @@ -33,7 +39,7 @@ Stop any non-essential indexing before you begin the upgrade procedure to elimin ### Review breaking changes -It's important to determine how the new version of OpenSearch will fit into your environment. Review [Breaking changes]({{site.url}}{{site.baseurl}}/breaking-changes/) before beginning any upgrade procedures to determine if you will need to make adjustments in your workflow. For example, upstream or downstream components might need to be modified to be compatible with an API change when you upgrade to a new major version of OpenSearch. +It's important to determine how the new version of OpenSearch will fit into your environment. Review [Breaking changes]({{site.url}}{{site.baseurl}}/breaking-changes/) before beginning any upgrade procedures to determine if you will need to make adjustments in your workflow. For example, upstream or downstream components might need to be modified to be compatible with an API change. ### Review the OpenSearch tools compatibility matrices @@ -54,36 +60,36 @@ Some examples include `opensearch.yml`, `opensearch_dashboards.yml`, plugin conf ### Take a snapshot -We recommend that you back up your cluster state and indexes using [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/). If you use the security plugin, make sure to read [A word of caution]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/#a-word-of-caution) for details about backing up and restoring your security settings. +We recommend that you back up your cluster state and indexes using [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/). If you use security features, make sure to read [A word of caution]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/#a-word-of-caution) for details about backing up and restoring your security settings. ## Upgrade methods Choose an appropriate method for upgrading your cluster to a new version of OpenSearch based on your requirements. -- [Rolling upgrade](#rolling-upgrade) is upgrading nodes one at a time without stopping the cluster. +- [Rolling upgrade](#rolling-upgrade) is the process of upgrading nodes one at a time without stopping the cluster. - [Cluster restart upgrade](#cluster-restart-upgrade) is the process of upgrading services while the cluster is stopped. Upgrades spanning more than a single major version of OpenSearch will require additional effort due to the need for reindexing. For more information, refer to the [Reindex]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/) API. See the [Lucene version reference](#lucene-version-reference) table included later in this guide for help planning your data migration. ### Rolling upgrade -Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Data may continue to be ingested, analyzed and queried as nodes are invididually stopped, upgraded, and restarted. A variation of the rolling upgrade, referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. You might perform node replacement if you are upgrading the underlying host(s) as well. +Rolling upgrades are a great option if you want to keep your cluster operational throughout the process. Data may continue to be ingested, analyzed, and queried as nodes are invididually stopped, upgraded, and restarted. A variation of the rolling upgrade, referred to as "node replacement," is exactly the same process except hosts or containers are not reused for the new node. You might perform node replacement if you are upgrading the underlying host(s) as well. -OpenSearch nodes cannot join a cluster if the cluster manager is running a newer version of OpenSearch than the node requesting membership. To avoid this issue, you upgrade cluster manager-eligible nodes last. +OpenSearch nodes cannot join a cluster if the cluster manager is running a newer version of OpenSearch than the node requesting membership. To avoid this issue, upgrade the cluster manager-eligible nodes last. See [Rolling Upgrade]({{site.url}}{{site.baseurl}}/install-and-configure/upgrade-opensearch/rolling-upgrade/) for details about the process. ### Cluster restart upgrade -OpenSearch administrators might choose to perform a cluster restart upgrade for several reasons. For example, if the administrator doesn't want to perform maintenance on a running cluster, or if the cluster is being migrated to different infrastructure. +OpenSearch administrators might choose to perform a cluster restart upgrade for several reasons. For example, if the administrator doesn't want to perform maintenance on a running cluster, or if the cluster is being migrated to a different environment. -Unlike a rolling upgrade, where only one node is offline at a time, a cluster restart upgrade requires you to stop OpenSearch and OpenSearch Dashboards on all nodes in the cluster before proceeding. After the nodes are stopped, a new version of OpenSearch is installed. Then, OpenSearch is started and the cluster bootstraps to the new version. +Unlike a rolling upgrade, where only one node is offline at a time, a cluster restart upgrade requires you to stop OpenSearch and OpenSearch Dashboards on all nodes in the cluster before proceeding. After the nodes are stopped, a new version of OpenSearch is installed. Then OpenSearch is started and the cluster bootstraps to the new version. ## Compatibility OpenSearch nodes are compatible with other OpenSearch nodes running any other *minor* version within the same *major* version release. For example, 1.1.0 is compatible with 1.3.7 because they are part of the same *major* version (1.x). Additionally, OpenSearch nodes and indexes are backwards-compatible with the previous major version. That means, for example, that an index created by an OpenSearch node running any 1.x version could be restored from a snapshot to an OpenSearch cluster running any 2.x version. -OpenSearch 1.x nodes are compatible with nodes running Elasticsearch 7.x, but the existence of a mixed-version environment should not extend beyond cluster upgrade activities. +OpenSearch 1.x nodes are compatible with nodes running Elasticsearch 7.x, but the longevity of a mixed-version environment should not extend beyond cluster upgrade activities. {: .tip} Index compatibility is determined by the version of [Apache Lucene](https://lucene.apache.org/) that created the index. If an index was created by an OpenSearch cluster running version 1.0.0, then the index could be used by any other OpenSearch cluster running up to the latest 1.x or 2.x release. See the [Index compatibility reference](#index-compatibility-reference) table for Lucene versions running in OpenSearch 1.0.0 and later and [Elasticsearch](https://www.elastic.co/) 6.8 and later. @@ -92,7 +98,7 @@ If your upgrade path spans more than a single major version, and you want to ret ### Index compatibility reference -If you plan to retain old indexes after the OpenSearch version upgrade, then you might need to reindex or reingest the data. Refer to the table below for Lucene versions across recent OpenSearch and Elasticsearch releases. +If you plan to retain old indexes after the OpenSearch version upgrade, then you might need to reindex or reingest the data. Refer to the following table for Lucene versions across recent OpenSearch and Elasticsearch releases.