Upgrading Amazon OpenSearch domain from v2.x to 3.x: Prerequisites, Breaking changes, and Best practices
3 minute read
Content level: Advanced
0
Amazon OpenSearch Service now supports OpenSearch 3.x, which introduces significant performance improvements through Apache Lucene 10, JVM 21, and enhanced vector search capabilities. Upgrading from 2.x to 3.x is a major version upgrade that includes breaking changes and requires pre-upgrade preparation. This article walks through the mandatory prerequisites, key considerations, and a recommended approach to ensure a smooth upgrade with minimal risk.
1. Upgrade Path (Mandatory)
- Domain must be on OpenSearch 2.19 before upgrading to any 3.x version
- Direct upgrade from older 2.x versions (e.g., 2.15, 2.17) to 3.x is not supported
- Upgrading Amazon OpenSearch Service domains
- Document history for Amazon OpenSearch Service
- Breaking changes
- OpenSearch and OpenSearch Dashboards 3.6.0 Release Notes
2. Key Things to Consider Before Upgrading
| Item | What to Do |
|---|---|
| Deprecated Index Settings | When upgrading from OpenSearch 2.19 to OpenSearch 3.x, you may need to address incompatible index settings. These were deprecated earlier in 2.x and will lead to an upgrade check validation failure if not removed: - index.knn.algo_param.ef_construction - index.knn.algo_param.m - index.knn.space_type - index.store.hybrid.mmap.extensions |
| Old Indices | If your domain contains indexes created in OpenSearch 1.3, Elasticsearch 7.10, or earlier versions, you must reindex them before upgrading to OpenSearch 3.x. OpenSearch 3.x doesn't support these older indexes, regardless of whether they're in hot, UltraWarm, or cold storage. To reindex incompatible UltraWarm or cold indexes. - Migrate the indexes to hot storage - Reindex the data - Migrate the indexes back to warm or cold storage |
| Major Changes | Major ones in 3.x include: - Lucene 10 upgrade - JVM 21 baseline - Removal of Java Security Manager - Several plugin and API changes |
| Domain Size | Larger domains may need more time and careful capacity planning. |
3. Will it require Blue/Green Deployment?
Yes, version upgrades on Amazon OpenSearch Service always use a Blue/Green deployment.
- AWS creates a new environment with the new version, migrates data, and then switches traffic.
- There is zero downtime for search and indexing in most cases.
- OpenSearch Dashboards may be briefly unavailable during the switch.
4. Major Benefits of Upgrading to 3.x
- Significant Performance Gains (Lucene 10):
- Lower search latency compared to 2.x
- Much better vector search performance
- Improved range queries and aggregations
- Better Query Insights (Live Queries, enhanced dashboard, failure tracking)
- Stronger Agentic AI & Observability capabilities
- Future-proofing — New features and security updates will only come to 3.x
- Better resource efficiency and cost optimization in many workloads |
5. Recommended Upgrade Approach
- Test Environment — Clone your domain or restore a snapshot to a test domain and upgrade first.
- Pre-upgrade Checklist:
- Remove deprecated index settings
- Reindex old indices
- Take a fresh manual snapshot
- Upgrade using AWS Console or CLI (in-place upgrade).
- Post-upgrade:
- Monitoring JVMMemoryPressure, CPU, Query Insights
- Test critical search queries and dashboards.
- Topics
- Analytics
- Language
- English
No comments
Relevant content
- AWS OFFICIALUpdated 3 years ago
- AWS OFFICIALUpdated 3 days ago
