Upgrading Search with OpenSearch Cluster Software

Upgrade a cluster's software version with a software upgrade.

Upgrade Methods

You can upgrade your OpenSearch cluster to a newer software version to access new features and functionality. OpenSearch supports several concurrent versions, so you can keep your OpenSearch cluster up-to-date with the latest enhancements. This topic describes the upgrade methods, considerations, and supported upgrade paths.

Choose one of the following methods to upgrade your OpenSearch cluster:

Clone and upgrade: (Recommended) Create a clone of your OpenSearch cluster and upgrade the cloned cluster to the required version. Use this approach to minimize risk and downtime, and to test the upgrade before switching production traffic to the new cluster.
Direct upgrade: Upgrade your existing OpenSearch cluster to the required version in place. Use this method for small or non-critical clusters where brief downtime is acceptable. This option is also known as "in-place upgrade."
Snapshot and restore: Use this method for a clean migration to a new OpenSearch cluster version, especially when you need to change configurations such as instance type, region, or architecture during the upgrade. Follow these steps to use this method of upgrade:
1. Create a snapshot of your current OpenSearch cluster. For instructions, see Creating a Cluster Backup.
2. Create a new OpenSearch cluster with the required software version.
3. Restore the snapshot in the new OpenSearch cluster. For instructions, see Restoring a Backup from a Cluster.

Limitations and Considerations for Upgrades

Consider the following limitations and considerations regarding inline upgrades:

After you start a direct upgrade, you can't stop or cancel the process. We recommend that you create a backup before starting the upgrade.
You can only upgrade to a newer OpenSearch software version. You can't downgrade to an older version.
If any index in your cluster uses the RAG pipeline, upgrading directly to version 3.2.0 fails. Use the snapshot and restore method as a workaround. RAG is fully supported on OpenSearch version 3.2.0.

Software Upgrade Paths

You can upgrade an OpenSearch cluster to a newer version, but only one major version at a time. The recommended upgrade path is outlined in the following table:


Current Version	Upgraded Version
1.x	2.19.1
2.x	2.19.1
2.19.1	3.2.0

Note

Versions 1.2.4 and 2.3.0 are deprecated, so you can upgrade them both directly to a version listed in the preceding table. For more information, see Search with OpenSearch Supported Versions.

Access the Clusters list in the Console to check whether a cluster is eligible for a software upgrade. Any clusters that are upgrade eligible include the text Upgrade in the Software version column. For instructions on accessing the Clusters list, see Listing Search with OpenSearch Clusters.

Upgrading the Software

1. On the Clusters list page, find the OpenSearch cluster that you want to work with. If you need help finding the list page or the cluster, see Listing Search with OpenSearch Clusters.
2. From the Actions menu for the OpenSearch cluster, select Upgrade.
3. On the Upgrade panel, select one of the following options:
  
  Upgrade current cluster: Upgrades the version of this cluster. Major version upgrades might have downtime.
  
  Create a clone and apply upgrade to clone: Use this feature to apply the upgrade to a clone so you can run tests. We recommend selecting this option for major upgrades to avoid any production traffic downtime because of any issues with the upgrade.
4. Select the software version from the Available software versions list. The current version is initially displayed.
5. Select Upgrade.
Use the oci opensearch cluster upgrade command and required parameters to perform an inline (minor build version) upgrade for a cluster.
Upgrading the Current Cluster
To upgrade the current cluster, set the is-clone parameter as false:
oci opensearch cluster upgrade --opensearch-cluster-id cluster_ocid --desired-software-version desired_OpenSearch_version --original_cluster_display_name original_cluster_display_name --upgrade-type [MAJOR | MINOR] --is-clone false [OPTIONS]
The original_cluster_display_name parameter is required to validate that the cluster ID has the same display name.

For a complete list of flags and variable options for CLI commands, see the Command Line Reference.
Cloning the Cluster and Applying the Upgrade
To create a clone of the cluster and apply the upgrade to the clone, set the is-clone parameter as true:
oci opensearch cluster upgrade --opensearch-cluster-id cluster_ocid --desired-software-version desired_OpenSearch_version --original_cluster_display_name original_cluster_display_name --upgrade-type [MAJOR | MINOR] --is-clone true [OPTIONS]
Run the UpgradeOpenSearchCluster operation to perform an inline (minor build version) upgrade for a cluster.
Upgrading the Current Cluster
Set the .isClone() parameter to false. For example:
```
.isClone(false)
```
Cloning the Cluster and Applying the Upgrade
Set the .isClone() parameter to true. For example:
```
.isClone(true)
```

OpenSearch Breaking Changes

For information on OpenSearch deprecations associated with version 3.x, including upgrades and deprecations, see the following OpenSearch site:

https://docs.opensearch.org/latest/breaking-changes/#300

Information regarding other OpenSearch versions are listed in the site as well.

Archive Settings

OpenSearch 3.x versions rename the deprecated settings with the prefix archived. All archive settings are removed during upgrade. Here is the list of deprecated settings:

thread_pool.test.max_queue_size
thread_pool.test.min_queue_size
index.store.hybrid.mmap.extensions
knn.plugin.enabled
index.knn.algo_param.ef_construction
index.knn.algo_param.m
index.knn.space_type
plugins.sql.delete.enabled
opendistro*
plugins.sql.pagination.api

Oracle Cloud Infrastructure Documentation