OpenSearch Migration Guide: From Elasticsearch and Between Versions

Migrating to OpenSearch — whether from Elasticsearch or between OpenSearch versions — requires careful planning around compatibility, data migration, client updates, and plugin differences. This guide covers the practical engineering steps for each migration path.

Migration Paths

Elasticsearch → OpenSearch

OpenSearch forked from Elasticsearch 7.10.2. Migration compatibility depends on your Elasticsearch version:

OpenSearch Version Upgrades

OpenSearch supports rolling upgrades between consecutive minor versions and from the last minor of one major to the first minor of the next. Check the OpenSearch compatibility matrix for your specific versions.

Snapshot-Based Migration (Recommended)

The safest migration approach uses shared snapshots — it doesn't touch the source cluster and can be tested repeatedly.

Step 1: Register a Snapshot Repository on the Source

# On Elasticsearch source cluster
PUT /_snapshot/migration-repo
{
  "type": "s3",
  "settings": {
    "bucket": "my-migration-bucket",
    "region": "us-east-1"
  }
}

Step 2: Create a Snapshot

PUT /_snapshot/migration-repo/migration-snapshot
{
  "indices": "*",
  "ignore_unavailable": true,
  "include_global_state": false
}

Set include_global_state: false to skip cluster settings that may be incompatible.

Step 3: Register the Same Repository on OpenSearch

# On OpenSearch target cluster
PUT /_snapshot/migration-repo
{
  "type": "s3",
  "settings": {
    "bucket": "my-migration-bucket",
    "region": "us-east-1"
  }
}

Step 4: Restore the Snapshot

POST /_snapshot/migration-repo/migration-snapshot/_restore
{
  "indices": "*",
  "ignore_unavailable": true,
  "include_global_state": false,
  "rename_pattern": "(.+)",
  "rename_replacement": "restored-$1"
}

Using rename_pattern lets you restore alongside existing indices to verify data before switching.

Step 5: Verify Data

# Compare document counts
GET /restored-my-index/_count

# Spot-check queries
GET /restored-my-index/_search
{
  "query": { "match_all": {} },
  "size": 5
}

Rolling Upgrade (In-Place)

For Elasticsearch 7.x to OpenSearch migrations on the same cluster nodes:

1. Disable shard allocation:

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

2. Stop and flush synced:

   POST /_flush/synced
   

3. Upgrade one node at a time: Stop the Elasticsearch process, install OpenSearch, start the node. Wait for it to rejoin and all shards to recover before proceeding to the next node.

4. Re-enable allocation after all nodes are upgraded:

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

Rolling upgrades carry more risk than snapshot-based migration. If something goes wrong mid-upgrade, you have a mixed-version cluster that's difficult to recover. Always have a snapshot backup before starting.

Client and API Changes

REST API Compatibility

Most Elasticsearch 7.x REST APIs work unchanged in OpenSearch. Key differences:

• Security plugin: OpenSearch uses its own security plugin (formerly Open Distro) instead of X-Pack. Authentication endpoints change from /_security/* to /_plugins/_security/*.
• Alerting, anomaly detection, ISM: These are OpenSearch plugins with different API paths than their Elastic equivalents.
• Type removal: Like Elasticsearch 7.x, OpenSearch doesn't support multiple types per index.
• Licensed features: Features that were X-Pack licensed in Elasticsearch (SQL, ML, alerting, security) are free in OpenSearch but may have different APIs.

Client Library Changes

Client migration is typically straightforward — change the package import and connection initialization. Query DSL syntax is identical.

# Before (Elasticsearch)
from elasticsearch import Elasticsearch
es = Elasticsearch(['https://es-host:9200'])

# After (OpenSearch)
from opensearchpy import OpenSearch
os_client = OpenSearch(
    hosts=[{'host': 'os-host', 'port': 9443}],
    use_ssl=True
)

Plugin and Feature Mapping

ILM to ISM Migration

If you use Elasticsearch ILM policies, you'll need to recreate them as ISM policies in OpenSearch. The concepts map closely but the syntax differs:

Elasticsearch ILM:

{
  "policy": {
    "phases": {
      "hot": { "actions": { "rollover": { "max_size": "50gb" } } },
      "delete": { "min_age": "30d", "actions": { "delete": {} } }
    }
  }
}

OpenSearch ISM:

{
  "policy": {
    "default_state": "hot",
    "states": [
      {
        "name": "hot",
        "actions": [{ "rollover": { "min_size": "50gb" } }],
        "transitions": [{ "state_name": "delete", "conditions": { "min_index_age": "30d" } }]
      },
      {
        "name": "delete",
        "actions": [{ "delete": {} }]
      }
    ]
  }
}

Handling Mapping Incompatibilities

From Elasticsearch 8.x

Elasticsearch 8.x introduced changes that OpenSearch doesn't support:

• Runtime fields: Not supported in OpenSearch. Convert to scripted fields or materialized fields.
• _doc endpoint deprecation changes: OpenSearch still supports _doc endpoint.
• New field types: Some 8.x field types (e.g., unsigned_long added in 8.x) may need mapping adjustments.

For 8.x migrations, export your mappings, review for incompatibilities, adjust, and create indices on OpenSearch before restoring data.

Migration Checklist

1. Inventory your cluster: Document indices, mappings, templates, ILM policies, ingest pipelines, roles, and users.
2. Check plugin compatibility: List all Elasticsearch plugins and find OpenSearch equivalents.
3. Update client libraries: Switch to OpenSearch client libraries and test in a staging environment.
4. Create a snapshot backup: Always have a restore point before any migration.
5. Test in staging: Restore your snapshot to a staging OpenSearch cluster. Run your application test suite against it.
6. Migrate security configuration: Recreate roles, users, and role mappings in OpenSearch Security.
7. Convert ILM to ISM policies: Recreate lifecycle management policies in OpenSearch's ISM format.
8. Update ingest pipelines: Most work unchanged, but verify any that use processor types specific to Elastic.
9. Switch DNS/load balancer: Point your application traffic to the OpenSearch cluster.
10. Monitor post-migration: Watch for query errors, performance regressions, and client compatibility issues for the first 48 hours.

Frequently Asked Questions

Q: Can I run Elasticsearch and OpenSearch side by side during migration?

Yes. This is the recommended approach. Run both clusters, dual-write new data (or replicate via snapshot/restore), and gradually shift read traffic to OpenSearch. This gives you a rollback path.

Q: Will my Kibana dashboards work in OpenSearch Dashboards?

OpenSearch Dashboards forked from Kibana 7.10.2. Dashboards, visualizations, and saved objects from Kibana 7.x can be exported and imported into OpenSearch Dashboards with minor adjustments. Kibana 8.x objects may require manual recreation.

Q: How long does a snapshot-based migration take?

Snapshot creation time depends on data size and I/O throughput. Restoring is typically faster since it reads sequentially from object storage. For a 1 TB cluster, expect 1–3 hours for snapshot creation and 30–90 minutes for restore, depending on network and storage performance.

Q: Is there a migration tool that automates this?

The OpenSearch Migration Assistant provides tools for metadata migration, snapshot-based data transfer, and live traffic replay for validating compatibility.

Q: What about performance differences between Elasticsearch and OpenSearch?

For most workloads, performance is comparable. OpenSearch has diverged in some areas (segment replication, searchable snapshots implementation), so benchmark your specific query patterns on a staging cluster before committing to production migration.