Elasticsearch to OpenSearch Migration: A Step-by-Step Guide

This guide assumes you have chosen OpenSearch. If you have not, the comparison of licences, features and managed services is on the OpenSearch vs Elasticsearch page. Two facts frame the timing.

Licence. Elastic moved Elasticsearch and Kibana source from Apache 2.0 to SSPL and the Elastic License with 7.11 in 2021. On 29 August 2024 it announced AGPLv3 as an added option for the free portions of the source, alongside SSPL and ELv2, while the Elastic License 2.0 continues to apply to Elastic's own distribution. OpenSearch is Apache 2.0. If your reason to move is a licence you can use without restriction, OpenSearch fits; if you only need an OSI-approved source licence for Elasticsearch, AGPLv3 now exists.

Support dates. Elastic ended maintenance for 7.17 on 15 April 2025 and support on 15 January 2026. For 8.x, maintenance ends 15 January 2027 and support 15 July 2027. A cluster on 7.17 is already past support, so a migration plan has a real deadline. While you plan, patched builds of Elasticsearch 7.10.2 and 7.17 from OSSeva keep a self-managed cluster covered.

OpenSearch's FAQ states that it is compatible with indices created by Elasticsearch 6.0 up to 7.10, that rolling upgrades are supported from Elasticsearch OSS 7.0 to 7.10, that 6.x needs a cluster restart upgrade, and that upgrading from Elasticsearch 7.11 or later is not supported. Treat snapshot restore of later versions as unsupported and plan to reindex.

Classify every dependency as compatible, needing a client swap, or needing redesign. The inventory has five parts: every client library and version across languages; plugins and licensed features in use (machine learning, alerting, security features, transforms); index templates, mappings and pipelines; ILM and snapshot policies; and Kibana saved objects. Test the ambiguous cases against a real OpenSearch cluster instead of trusting a compatibility matrix.

Decide in the assessment which workloads should not move. In a published service example, an assessment for a digital media platform produced a concrete list of client upgrades and two feature redesigns, and left two poor candidates in place.

Every path starts from snapshots, either as the migration method or as the way back. OpenSearch's migration guidance says snapshots are forward compatible by one major version and that larger gaps need an intermediate cluster, a reindex and a new snapshot. It also advises excluding the .opendistro_security index from snapshots and planning security configuration separately.

Verify the repository before relying on it. In a published service example, an insurance services provider learned during a disaster-recovery test that restores failed partway: the repository had been reconfigured without verification, and some snapshots were outside the restore range of the newer target version. The fix was to verify every repository, restore older indices through an intermediate version and reindex forward, and schedule a restore test. Do that test before the migration, not during it.

The reindex API can pull documents from another cluster. Allow-list the source in opensearch.yml on the target, create the destination indices first from your templates so mappings are explicit, then start the copy asynchronously:

# opensearch.yml on the OpenSearch cluster
reindex.remote.allowlist: ["es-old.example.com:9200"]

POST _reindex?wait_for_completion=false&slices=auto
{
  "source": {
    "remote": { "host": "https://es-old.example.com:9200",
               "username": "reindex", "password": "<secret>" },
    "index": "orders-2026.09"
  },
  "dest": { "index": "orders-2026.09" }
}

slices parallelises the copy, requests_per_second throttles it, and the Tasks API reports progress. OpenSearch documents source.remote for a remote OpenSearch cluster, so prove it against your exact Elasticsearch version on a rehearsal copy before you plan around it. Work in waves: cold indices first, then the hot ones, finishing with an incremental pass and an alias swap.

Migration Assistant is the OpenSearch project's Kubernetes-native tool for moving data, metadata and live traffic; Amazon EKS is the recommended path on AWS. It offers snapshot-based backfill with Reindex-from-Snapshot, which puts little load on the source, and zero-downtime migration using Capture and Replay of live traffic. It migrates index settings, mappings, templates, component templates and aliases.

Know its edges before you plan around it. These are out of scope and migrate by hand: data streams, ISM and ILM policies, ingest pipelines, security configuration, cluster settings and Dashboards objects. Documented limits include a default shard size limit of 80 GiB, no support for snapshots using zstd codecs, no preservation of auto-generated document IDs under Capture and Replay (clients must supply IDs), and a recommendation to use live capture below about 4 TB a day of traffic. Elasticsearch and OpenSearch sources need the repository-s3 plugin for S3 snapshots.

This is the change teams underestimate. OpenSearch's documentation says Elasticsearch OSS 7.10.2 clients should work with OpenSearch 1.x, but the latest versions of those clients may include license or version checks that break compatibility. For OpenSearch 2.0 and later it says no Elasticsearch clients are fully compatible, and that mixing them carries a high risk of errors. Use the official OpenSearch clients for Java, Python, JavaScript, Go, Ruby, PHP, .NET and Rust, and note that the Java high-level REST client and the high-level Python client are deprecated.

The Query DSL is largely shared, so most query bodies carry over. What changes is construction code, authentication, response types and any use of features that exist only in newer Elasticsearch releases. Migrate service by service behind a feature flag, with the old and new clients running side by side in tests.

Roles and users do not migrate with the data. The Security plugin provides TLS, authentication backends (internal users, LDAP, Active Directory, SAML, OpenID Connect), roles mapped to users, tenants for Dashboards, field- and document-level security, and audit logging. Translate each Elasticsearch role into an OpenSearch role and role mapping, tie the mappings to your identity provider, and test with representative identities, because a wrong mapping can silently hide documents from a whole user group without any cluster-health signal.

Kibana to OpenSearch Dashboards. Dashboards was forked from Kibana 7.10.2. Export saved objects as NDJSON and import them under Dashboards Management, Saved objects. Expect errors for objects created in newer Kibana versions, which the OpenSearch forum documents, and plan to rebuild those visualizations.

ILM to ISM. Index State Management describes a policy as states, actions and transitions, and attaches policies to new indices through an ism_template with index patterns. Rewrite each ILM policy by hand: Migration Assistant does not move them.

Alerts. Watcher definitions need to be recreated in the OpenSearch alerting plugin.

• Counts and aggregates per index, compared between clusters.
• Query parity: replay production queries against both and diff the results. Scoring and some aggregation behaviour have drifted between the projects, so compare ranking on the queries your users depend on.
• Load test at production concurrency with real shard layout.
• Dual-write new documents to both clusters during the final waves, so the old cluster stays current until the switch.
• Cutover: point read and write aliases at the OpenSearch indices, repoint clients, and keep the old cluster read-only for a fixed period.
• Rollback: flipping the alias back works while dual-write is still running. After that, rollback means restoring from the snapshot you took first.

AceMQ handles Elasticsearch 7.10.x to OpenSearch migrations, self-managed or on Amazon OpenSearch Service: client library and plugin compatibility assessment, reindex-from-remote cutover with an alias swap, and 24/7 support afterwards. Start at OpenSearch consulting and migration, or see OpenSearch support and Elasticsearch support if you need cover while both clusters run.

Sources: OpenSearch FAQ, Migration Assistant, its version support and limits, snapshot and restore for migration, the reindex API, clients, security, ISM and saved objects; Elastic's licensing FAQ, AGPL announcement and end-of-life dates. Check the docs for your target OpenSearch version before a migration window.