Required Client Changes - opensearch-project/opensearch-migrations GitHub Wiki

The goal of the Migration Assistant is to streamline the process of migrating from one location or version of Elasticsearch/OpenSearch to another. However, completing a migration sometimes requires resolving client compatibility issues before they can communicate directly with the target cluster.

It's crucial to understand and plan for any necessary changes before beginning the migration process. The previous page on breaking changes between versions is a useful resource for identifying potential issues.

Data Transformations and Client Impact

Any time you apply a transformation to your data, such as:

Changing index names
Modifying field names or field mappings
Splitting indices with type mappings

These changes may need to be reflected in your client configurations. For example, if your clients are reliant on specific index or field names, you must ensure that their queries are updated accordingly.

We recommend running production-like queries against the target cluster before switching over actual production traffic. This helps verify that the client can:

Communicate with the target cluster
Locate the necessary indices and fields
Retrieve the expected results

For complex migrations involving multiple transformations or breaking changes, we highly recommend performing a trial migration with representative, non-production data (e.g., in a staging environment) to fully test client compatibility with the target cluster.

Troubleshooting

Migrating from Elasticsearch (Post-Fork) to OpenSearch

Migrating from post-fork Elasticsearch (7.10.2+) to OpenSearch presents additional challenges because some Elasticsearch clients include license or version checks that can artificially break compatibility.

No post-fork Elasticsearch clients are fully compatible with OpenSearch 2.x. We recommend switching to the latest version of the OpenSearch Clients ↗.

Inspecting the tuple output