Oracle Cloud Infrastructure Documentation

Upgrading Search with OpenSearch Cluster Software

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

Search with OpenSearch supports several concurrent versions of OpenSearch. For existing clusters using older versions, you can upgrade the cluster to use the functionality available in the latest version of OpenSearch.

The upgrade process depends on whether you're doing a major version upgrade or a minor version upgrade. A major version upgrade is indicated by a change in the first number in the build number, for example, 2.19.1 to 3.2.0. A minor version upgrade is indicated by a change in the second number in the build number, for example, 2.11.0 to 2.15.0.

You can upgrade the software version of OpenSearch cluster using the following methods:

The Direct upgrade and Clone and upgrade methods are described later in this topic.

Note

Consider the following limitations and considerations regarding inline upgrades:
  • After the inline upgrade process is started, you can't stop or cancel the process. We recommend that you create a backup of the cluster.
  • You can only upgrade a cluster to a newer OpenSearch software version, you can't downgrade to an older OpenSearch software version.
  • Upgrading to version 3.2.0 fails if an index with RAG pipeline is present in cluster, current workaround is to use snapshot and restore route for upgrading. RAG is however fully supported on the upgraded 3.2.0 cluster. Work is in progress to address both these issues.

Recommended Upgrade Paths

Pre Upgrade Version Post Upgrade Version
1.2.4 2.11.0
2.3.0 2.11.0
2.11.0 2.15.0
2.15.0 2.18.0
2.18.0 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 version 2.11.0. 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. Configure the is-clone parameter as false or true to specify whether you're upgrading the current cluster or are creating a clone of the cluster and am applying the upgrade to the clone.

    Run the following command to upgrade the current cluster:

    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]

    Run the following command to create a clone and apply the upgrade to the clone:

    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]

    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.

  • Run the UpgradeOpenSearchCluster operation to perform an inline software upgrade for a cluster.

Archive Settings

OpenSearch 3.x versions rename the deprecated settings with the prefix archived. All archived 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