OpenSearch 2 to 3 Upgrade Guide: Breaking Changes, Rolling Upgrade Rules and Amazon OpenSearch Service

The short answer

Get every node to 2.19 first: it is the minimum cluster version for an upgrade to 3.x, and rolling upgrades only work between adjacent major versions. Before the upgrade, reindex anything created before 2.x, remove the index and cluster settings that 3.0 deleted, and move any process that sets its own Java to JDK 21. Then upgrade one node at a time, data nodes first and cluster manager nodes last. OpenSearch nodes cannot be downgraded, so the way back is a new installation restored from a snapshot you took beforehand.

There is no deadline forcing the move today. The OpenSearch project lists 2.x as in maintenance until 4.0 reaches general availability, with 2.19.6 released on 2 July 2026 and further 2.19 releases scheduled. 3.x is the current line, with 3.9.0 released on 29 September 2026. 3.0 moved to Lucene 10 and JDK 21, so the upgrade is worth planning before a 2.x fix is the reason you need it.

Supported upgrade paths

OpenSearch documents four methods. A rolling upgrade needs no new infrastructure but supports only adjacent major versions. Snapshot and restore needs a new cluster and downtime or change data capture, and leaves the old cluster untouched for reversion. Remote reindex copies data into a new cluster with no downtime, at the cost of load on the source. Migration Assistant handles multi-version hops with live capture and can revert, but needs extra setup and infrastructure.

Pre-upgrade checklist

• Cluster status green, with no unassigned or relocating shards.
• A snapshot of cluster state and indexes in a remote repository, such as S3, Google Cloud Storage, Azure Blob Storage or HDFS.
• Copies of opensearch.yml, jvm.options, plugin configuration and TLS certificates from opensearch/config and opensearch-dashboards/config.
• Every plugin checked against the target version. Plugin versions must match the OpenSearch major, minor and patch version exactly, so third-party plugins need a 3.x build.
• Logstash, Beats, Data Prepper, client libraries and anything else that talks to the cluster checked against OpenSearch's tools compatibility matrices.
• Non-essential indexing paused for the window.

Breaking change 1: JDK 21 and Lucene 10

OpenSearch 3.0 requires JDK 21 as the minimum Java runtime and upgrades to Lucene 10. Distributions that bundle a JDK handle the first part; nodes that point OPENSEARCH_JAVA_HOME or JAVA_HOME at a system JDK need that JDK to be 21 or later. Custom plugins must be rebuilt for 3.x and JDK 21 in any case.

GET _cat/nodes?v&h=name,version,jdk,node.role
GET _cat/plugins?v

Breaking change 2: indexes created before 2.x are not supported

Indexes created in versions earlier than 2.x, including system indexes, must be reindexed before the upgrade. This catches clusters that started life on OpenSearch 1.x or on Elasticsearch 7.10 and were upgraded in place, because the index keeps the version it was created with.

GET _all/_settings?human&filter_path=*.settings.index.version.created_string

Anything that does not report a 2.x version needs a reindex into a new index, created on 2.19, before the upgrade can proceed. Repoint aliases to the new index and delete the old one after checking document counts.

Breaking change 3: removed settings and plugins

grep -nE "override_main_response_version|thread_pool\.test|hybrid\.mmap|knn\.plugin\.enabled|opendistro" \
  /etc/opensearch/opensearch.yml

GET _all/_settings?filter_path=*.settings.index.knn.algo_param,*.settings.index.knn.space_type,*.settings.index.store.hybrid
GET _index_template?filter_path=**.knn.algo_param,**.knn.space_type,**.hybrid

Breaking change 4: stricter request limits

• Document IDs. The 512-byte limit is now enforced on every API, including bulk, which previously accepted longer IDs. Producers that build IDs from long URLs or composite keys will start getting rejections.
• JSON. Nesting depth is capped at 1,000 levels and property names at 50,000 units.
• Nested queries. A new index.query.max_nested_depth setting defaults to 20 levels.
• System indexes. Access to system indexes through the REST API, deprecated since 1.x, is gone.

Search ingestion code for ID construction and test a replay of real bulk traffic against a 3.x node before the upgrade; the bulk change shows up only under real data.

Breaking change 5: behaviour that changes quietly

• Scoring. The default BM25 implementation changed from LegacyBM25Similarity to BM25Similarity. The project says search quality is preserved, but if anything compares scores to a fixed number, such as a min_score threshold, retest it.
• Security plugin. Blake2b hashing now uses the salt parameter correctly, so hash values differ from 2.x. Check field masking or anonymisation that relies on stable hashes.
• Nodes API. total_indexing_buffer_in_bytes now returns raw bytes and total_indexing_buffer a human-readable value. Monitoring that parses them needs updating.
• Node roles. node.roles= set through an environment variable now creates a coordinating-only node, matching opensearch.yml.
• Searchable snapshots. Nodes serving searchable snapshot shards need the warm role; the search role no longer covers them. Change the roles before upgrading.
• Workload management. Query groups are now workload groups: the endpoint moved to wlm/workload_group and settings are prefixed wlm.workload_group.
• Analysis. The camel-case PathHierarchy tokenizer name is deprecated for path_hierarchy, and the Romanian analyser now normalises cedilla characters, so OpenSearch recommends reindexing Romanian text.

Breaking change 6: OpenSearch Dashboards

The discover:newExperience setting, the DataGrid table and the dashboards-visualizations plugin, including Gantt charts, were removed; OpenSearch suggests Vega or trace analytics instead. Legacy notebooks stored in the .opensearch-observability index are no longer supported, and must be migrated to the .kibana storage introduced in 2.17 before the upgrade.

The rolling upgrade, step by step

1. Confirm the cluster is green: GET _cluster/health?pretty.
2. Stop replica allocation while nodes go offline:

   PUT _cluster/settings
   { "persistent": { "cluster.routing.allocation.enable": "primaries" } }

3. Flush, to commit translog entries to Lucene: POST _flush.
4. Pick the next node, in this order: data nodes, then ingest, ML and coordinating nodes, then cluster manager-eligible nodes last. Newer nodes can join a cluster whose cluster managers run the older version, but not the other way round. GET _cat/nodes?v&h=name,version,node.role,master shows the current cluster manager.
5. Stop the node and confirm it has left the cluster. In Docker, keep the data volume.
6. Upgrade it. Debian and RPM installs keep their files in place; for a tarball, copy the old data directory, opensearch.yml, jvm.options and TLS certificates into the new installation.
7. Start it and confirm it rejoined with the new version: GET _nodes/<node-name>.
8. Re-enable allocation with "cluster.routing.allocation.enable": "all" and wait for green before the next node.

With cross-cluster replication, upgrade the follower cluster before the leader. For bidirectional replication, stop one direction, upgrade both clusters follower first, then resume it.

Amazon OpenSearch Service

AWS documents the same move as an in-place upgrade, with its own rules on the page "Upgrading Amazon OpenSearch Service domains":

• Domains on OpenSearch 1.3 or 2.x must upgrade to 2.19 before 3.x.
• The pre-upgrade check fails on the deprecated index settings index.knn.algo_param.ef_construction, index.knn.algo_param.m, index.knn.space_type and index.store.hybrid.mmap.extensions.
• Indexes created in OpenSearch 1.3, Elasticsearch 7.10 or earlier must be reindexed, including UltraWarm and cold indexes, which have to be moved to hot storage, reindexed and moved back, or deleted.
• Snapshots taken on OpenSearch 1.x or Elasticsearch 7.10 and earlier are incompatible with 3.x, and AWS says to delete them from manual snapshot repositories before the upgrade. Export anything you still need first.
• The upgrade runs pre-upgrade checks, takes a snapshot, then upgrades, which can take from 15 minutes to several hours. OpenSearch Dashboards may be unavailable for part or all of it. You cannot downgrade afterwards; AWS uses the snapshot to restore the domain only if the upgrade itself fails.

aws opensearch get-compatible-versions --domain-name my-domain
aws opensearch upgrade-domain --domain-name my-domain \
  --target-version OpenSearch_3.x --perform-check-only

Replace OpenSearch_3.x with a version string returned by the first command. A check-only run reports validation failures without upgrading. If you stream data in with Amazon Data Firehose or CloudWatch Logs, AWS asks you to confirm those services support the new version first.

Rollback limits

OpenSearch nodes cannot be downgraded. To revert a rolling upgrade you install the old version on new nodes and restore the snapshot taken before the upgrade, which loses everything indexed since that snapshot unless you can replay it from the source. If a rollback must be cheap, use snapshot and restore into a new 3.x cluster, or Migration Assistant, instead: the 2.19 cluster stays untouched until you switch traffic, and switching back is a DNS or load balancer change.

Where OSSeva fits

OSSeva does not offer a dedicated OpenSearch support service or patched OpenSearch builds. OpenSearch appears in OSSeva's search coverage as a migration target for Elasticsearch. OSSeva for Elasticsearch ships backported security fixes for self-managed Elasticsearch 7.10.2 and 7.17, and for 8.19 after Elastic ends 8.x maintenance on 15 January 2027. OSSeva Assure adds a reindex and client plan for 8.x or OpenSearch, and OSSeva Operate executes the migration and monitors the cluster 24/7. If you are still choosing between the two engines, read Elasticsearch vs OpenSearch; for the version dates, see OpenSearch end-of-life dates.

Frequently asked questions

Can I do a rolling upgrade from OpenSearch 2.x to 3.x?

Yes, from 2.19.0 or later. Rolling upgrades only work between adjacent major versions, and 2.19.0 is the minimum cluster version for an upgrade to 3.x.

Can I upgrade OpenSearch 1.3 directly to 3.0?

Not by rolling upgrade. Go to 2.19 first and reindex indexes created in 1.x, or move the data with snapshot and restore, remote reindex or Migration Assistant into a new 3.x cluster.

What Java version does OpenSearch 3 need?

JDK 21 or later.

Which Lucene version does OpenSearch 3 use?

OpenSearch 3.0.0 upgraded to Lucene 10.1.0.

Can I downgrade from OpenSearch 3 to 2?

No. OpenSearch nodes cannot be downgraded. Install 2.x on new nodes and restore a snapshot taken before the upgrade.

Is OpenSearch 2.x end of life?

No. The project lists 2.x in maintenance until OpenSearch 4.0 is generally available, and 2.19 releases continue.

How long does an Amazon OpenSearch Service upgrade to 3.x take?

AWS says from 15 minutes to several hours, after its pre-upgrade checks and snapshot. OpenSearch Dashboards may be unavailable during some or all of it.