Required Client Changes

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

The Replayer outputs that show the exact requests being sent to both the source and target clusters. Examining these tuples can help you identify any transformations between requests, allowing you to ensure that these changes are reflected in your client code. See In-flight Validation for details.

Related Links

For more information about OpenSearch clients, refer to the official documentation: