Elasticsearch to OpenSearch Migration Blueprint
A blueprint to migrate Elasticsearch to OpenSearch using snapshot-restore or reindex-from-remote, swapping to OpenSearch clients and validating query parity via blue-green cutover for an Apache 2.0-licensed search engine.
Overview
OpenSearch is the Apache 2.0-licensed fork of Elasticsearch 7.10, created after Elastic changed Elasticsearch to a non-open-source license. Teams that require a permissive open-source license, or who use Amazon OpenSearch Service, migrate to OpenSearch. Because OpenSearch shares its lineage with Elasticsearch 7.10, the data and API surface are very similar, but newer Elasticsearch features and clients diverge. This blueprint covers the move.
Phases
Assessment. Record the source Elasticsearch version. OpenSearch maps cleanly from 7.10; migrating from 7.11+ or 8.x needs extra care because of feature and client divergence. Inventory indices, mappings, ingest pipelines, and security/role configuration.
Cluster setup. Provision the OpenSearch cluster (self-managed or Amazon OpenSearch Service) sized to match the source. Configure security (the OpenSearch Security plugin replaces X-Pack security), TLS, and index templates.
Index migration. Move data with snapshot-and-restore via a shared repository (S3, shared filesystem), or reindex-from-remote for live transfer. Recreate ingest pipelines and index templates.
Client migration. Switch applications to the OpenSearch clients/SDKs; the Elasticsearch 8.x clients reject OpenSearch. Update queries that used Elastic-only features.
Cutover. Run blue-green: index into both, validate result parity, then switch read traffic to OpenSearch.
Key Risks and Mitigations
- Data consistency: Validate document counts and run representative queries against both clusters for parity before cutover.
- Client compatibility: Replace Elasticsearch clients with OpenSearch clients; test all query paths, since some Elastic features are absent.
- Downtime: Use snapshot-restore plus dual indexing (blue-green) so search stays available throughout.
Recommended Tooling
Snapshot-and-restore via an S3/shared repository; reindex-from-remote for live data; OpenSearch clients/SDKs; the OpenSearch Security plugin for auth; OpenSearch Dashboards (the Kibana fork) for operations.
Success Metrics
Search latency parity with the source, indexing throughput parity, and license compliance under Apache 2.0.
Prerequisites
Known source version, a snapshot repository, a sized OpenSearch cluster with security configured, updated client libraries, and a parity-validation plan.