Elasticsearch to OpenSearch Migration Guide - Part 1: Why Migrate and Pre-Migration Planning

Migrating from Elasticsearch to OpenSearch makes sense when an Apache 2.0 license, vendor neutrality or cost matters more to you than features that only Elastic ships. If you decide to go, success depends on planning: check what your source version and features can carry over, choose a migration method that fits your downtime budget, and define how you will validate and roll back.

This first part covers the decision itself and the planning steps that set the foundation for a successful migration.

Why migrate from Elasticsearch to OpenSearch?

What are the main reasons teams migrate?

The decision to migrate from Elasticsearch to OpenSearch typically stems from specific technical and business requirements.

Licensing. OpenSearch is licensed under Apache 2.0 and governed under the Linux Foundation. Elasticsearch's licensing has changed more than once: since 2024 its source code is available under a choice of SSPL 1.0, AGPLv3 or the Elastic License 2.0, while Elastic's own release builds are distributed under the Elastic License. AGPLv3 is an OSI-approved open source license, but its network-use obligations are a concern for some companies, particularly those offering managed services or embedding the engine in their products. Have your legal team review which license applies to how you deploy.

Cost. Some Elasticsearch capabilities require a paid subscription; for example, Learning to Rank is limited to certain subscription levels, and in our own tests hybrid fusion methods were unavailable on the default Basic license (see our hybrid scoring post). OpenSearch ships comparable capabilities as open source plugins, including:

• Security plugin with authentication, authorization, and encryption
• Alerting and anomaly detection for operational monitoring
• SQL and PPL query support
• Index State Management for automated index lifecycle
• Performance Analyzer for cluster diagnostics

Compare the specific features you use against Elastic's current subscription tiers rather than assuming either way.

When should you consider migration?

Organizations should prioritize Elasticsearch to OpenSearch migration when:

Multi-cloud deployments require flexibility. OpenSearch's vendor-neutral approach enables consistent deployments across cloud providers and on-premises infrastructure.

Compliance requirements mandate Apache-licensed or foundation-governed software. Some public sector, financial and healthcare organizations have procurement rules that favor it.

A major upgrade is due anyway. If you are on an older Elasticsearch release and face a multi-step upgrade, moving to OpenSearch can be the same amount of work as upgrading in place.

When should you stay with Elasticsearch?

Certain scenarios favor remaining with Elasticsearch:

• Active use of Elastic-specific features added after the fork that have no OpenSearch equivalent (check each one; OpenSearch has built its own versions of many, such as searchable snapshots)
• Deep integration with Elastic Cloud or Elastic's managed services
• Dependency on proprietary Elastic integrations not available in OpenSearch
• Existing enterprise support contracts with significant remaining terms

How do you plan an Elasticsearch to OpenSearch migration?

Which Elasticsearch versions can migrate directly?

OpenSearch was forked from Elasticsearch 7.10.2, and the two APIs have diverged since. You can't assume a post-fork feature exists on both sides, so check your source version against OpenSearch's Migration Assistant support matrix:

For 8.x sources, Migration Assistant supports post-fork features through compatibility handling, but some 8.x features have no OpenSearch equivalent, so test the metadata migration first.

Critical compatibility checks:

# Check installed plugins
GET _cat/plugins

# Verify index mappings
GET _mapping

# List index templates
GET _index_template

# Check cluster settings
GET _cluster/settings?include_defaults=true

Document all custom analyzers, tokenizers, and scripts that require migration. Migration Assistant moves documents, index settings, mappings, templates and aliases, but these need manual work:

• Ingest pipelines (recreate on the target, replacing any Elastic-only processors)
• ILM policies (recreate as OpenSearch Index State Management policies)
• Data streams (recreate on the target)
• Security configuration (configure the OpenSearch Security plugin separately)
• Kibana objects (export and import into OpenSearch Dashboards)
• Watcher configurations (migrate to OpenSearch Alerting)
• Machine learning and transform jobs (rebuild with OpenSearch equivalents)

Which migration strategy should you choose?

Select a migration strategy based on cluster size, downtime tolerance, and risk appetite:

1. Snapshot-based backfill

• Moves historical data from a snapshot rather than querying the live cluster, so it keeps load off the source
• OpenSearch's Migration Assistant does this with Reindex-from-Snapshot, which also lets you cross several major versions in one step
• Downtime: depends on whether you pair it with live traffic capture
• Risk: Low

2. Remote reindex

• Best for selective data migration
• Allows data transformation during migration
• No downtime for source cluster
• Risk: Medium (requires careful monitoring of source load)

3. Dual-write or capture and replay

• Zero-downtime migration
• Dual-write requires application changes; Migration Assistant's Capture and Replay instead records live traffic through a proxy and replays it on the target
• Enables gradual cutover and side-by-side comparison
• Risk: Higher complexity

4. Blue-green deployment

• Full cluster duplication
• Instant switchover capability
• Requires double infrastructure
• Risk: Low (with higher cost)

How do you reduce migration risk?

Identify and mitigate migration risks through systematic planning:

Data integrity risks:

• Implement checksums for critical indices
• Perform pre and post-migration document counts
• Validate aggregation results match source

Performance risks:

• Baseline current query latency and throughput before you start
• Size the target for the extra load of backfill running alongside production traffic
• Set OpenSearch JVM and node settings deliberately rather than copying them blindly

Operational risks:

• Document all API endpoints and client libraries in use
• Create rollback procedures for each migration phase
• Establish clear go/no-go decision criteria
• Test with one or two representative indices before migrating everything

Key takeaways

Successful Elasticsearch to OpenSearch migration begins with understanding your motivations and thoroughly planning the migration process. The decision to migrate should be based on:

• Licensing requirements and compliance needs
• Cost of the features you actually use
• Technical fit of OpenSearch for your workload
• Compatibility of your current Elasticsearch version and features

With proper planning and assessment, organizations can minimize risks and ensure a smooth transition to OpenSearch.

What's next?

With a plan in place, the execution work covers:

• OpenSearch cluster setup and configuration
• Data migration with snapshot backfill or reindexing
• Configuration migration (security, lifecycle policies, pipelines)
• Application and client library changes, then validation and cutover

If you want help planning or running the migration, see our OpenSearch consulting services.

Sources

• OpenSearch documentation, Is Migration Assistant right for you?
• OpenSearch documentation, Migration Assistant
• Elastic, Licensing FAQ
• Elastic documentation, Learning To Rank