Oracle Cloud Infrastructure Documentation

OpenSearch Cluster Software Upgrades

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

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

  • Snapshot and restore: Follow these steps:
    1. Create a snapshot from your current cluster. For instructions, see Creating an OpenSearch Cluster Backup.
    2. Create a new cluster of the required software version.
    3. Restore the snapshot in the new cluster. For instructions, see Restoring a Backup to a New OpenSearch Cluster.
  • Direct upgrade: Upgrade your cluster itself to the required version.
  • Clone and upgrade: Create a clone of your cluster and upgrade to the required version.

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

Note 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.
  • OpenSearch nodes and indexes are backward compatible with the previous major version.

Supported Upgrade Paths for Inline Upgrade

Pre Upgrade Version Post Upgrade Version
1.2.4 2.3
2.3 2.11
2.11 2.15
2.15 2.18
2.18 2.19.1
2.19.1 3.2.0

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 OpenSearch Clusters.

    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 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.

    The value for upgrade-type must be MINOR.

    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. Configure the upgradeType as Minor.

Performing a Major Upgrade

Follow the previous steps for in this topic for upgrading the cluster's software version. Select version 3.2.0 or higher from the Available software versions list.

Note

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.

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