Migration Paths

Migration Paths

This page describes the supported migration paths, version compatibility, and what components can be migrated using Migration Assistant.

Determining your source version

Before configuring a migration, identify your source cluster version:

# Query the cluster directly
curl -s <source-endpoint>/ | jq '.version.number'

# For Kubernetes deployments, check the image tag
kubectl get pods -n <namespace> -o jsonpath='{.items[*].spec.containers[*].image}'

Use the version string format expected by Migration Assistant configuration:

• Elasticsearch: ES 7.10, ES 6.8, ES 8.12
• OpenSearch: OS 1.3, OS 2.11

Supported source and target versions

Source Platform	Source Versions	Target Versions
Elasticsearch	1.x - 8.x	OpenSearch 1.x, 2.x, 3.x
OpenSearch	1.x	OpenSearch 1.x, 2.x, 3.x
OpenSearch	2.x	OpenSearch 2.x, 3.x
Apache Solr	8.x	OpenSearch 3.x

Version-specific guidance

Elasticsearch 1.x - 5.x:

• Legacy versions with significant mapping and settings differences
• Test with a subset of indexes first using index allowlists
• Some index settings may not be compatible and will be skipped

Elasticsearch 6.x:

• Requires handling for multiple mapping types per index
• Configure multiTypeBehavior in your migration config to specify how to handle multi-type indexes (e.g., merge types, split to separate indexes, or fail)
• Run workflow configure edit to see available options

Elasticsearch 7.x:

• Most compatible path due to shared codebase with OpenSearch 1.0
• Generally requires no special configuration

Elasticsearch 8.x:

• Supported with compatibility handling for post-fork features
• Some 8.x-specific features may not have OpenSearch equivalents
• Test metadata migration first to identify incompatibilities

OpenSearch to OpenSearch:

• Useful for cluster consolidation or major version upgrades
• Most straightforward migration path

Apache Solr 8.x:

• Solr migrations use a different architecture than Elasticsearch migrations — see Solr Migration Overview
• Document backfill: SolrReader reads Solr backup data (Lucene segment files), translates Solr schema.xml field types to OpenSearch mappings, and bulk-indexes documents
• Query traffic: The Transformation Shim translates Solr HTTP API requests (/solr/{collection}/select) to OpenSearch _search API in real time, helping validate a viable migration path before making application changes
• Schema translation: Solr field types (solr.TextField, solr.StrField, solr.IntPointField, etc.) are automatically mapped to OpenSearch equivalents (text, keyword, integer, etc.)
• Validation: Dual-target mode sends queries to both Solr and OpenSearch simultaneously and compares responses before cutover
• SolrCloud and standalone Solr deployments are both supported as sources

Supported platforms

Platform	Source	Target
Self-managed (on-premises)	✓	✓
Amazon OpenSearch Service	✓	✓
Amazon OpenSearch Serverless	✗	✓
Elastic Cloud	✓	✓
AWS EC2	✓	✓
Apache Solr (SolrCloud / Standalone)	✓	✗

Note: Amazon OpenSearch Serverless is supported as a target for document backfill and index metadata migration. Serverless collections must be pre-created via the AWS API; index creation within a collection is handled by the metadata migration tool. TIMESERIES and VECTOR collection types use server-generated document IDs; SEARCH collections preserve source IDs.

Component support

Fully supported

Component	Description
Documents	All documents in selected indexes
Index settings	Shard count, replica count, refresh interval, and other index-level settings
Index mappings	Field mappings, dynamic templates, and mapping parameters
Index templates	Legacy index templates
Component templates	Reusable template components (Elasticsearch 7.8+/OpenSearch)
Index template (composable)	Composable index templates that reference component templates
Aliases	Index aliases and their configurations

Not supported

Component	Reason	Workaround
Data Streams	Not currently supported	Manually recreate data streams on target
ISM policies	OpenSearch-specific feature with different syntax	Manually recreate policies on target
Security configuration	Cluster-specific, security-sensitive	Configure security separately on target
Kibana/Dashboards saved objects	Separate application data	Export/import using Dashboards UI
Ingest pipelines	May contain version-specific processors	Manually recreate or export/import
Snapshot repositories	Cluster-specific configuration	Configure separately on target
Cluster settings	Cluster-specific tuning	Configure separately on target
ILM policies	Elasticsearch-specific, replaced by ISM	Create equivalent ISM policies
Amazon OpenSearch Service UltraWarm	Not supported as source or target tier	UltraWarm data will be migrated into hot indexes

Solr component support

When migrating from Apache Solr, a different set of components is relevant:

Component	Supported	Notes
Documents	✓	Extracted from Solr backup Lucene segment files
Schema (field types & mappings)	✓	Solr schema.xml field types translated to OpenSearch mappings
Query translation (select)	✓	Transformation Shim converts Solr select queries to OpenSearch _search API
Facets	✓	Terms, range, date range, JSON facets, pivot facets
Highlighting	✓	Basic and advanced highlighting
Cursor pagination	✓	cursorMark translated to search_after
Solr plugins	✗	Custom Solr plugins must be reimplemented as OpenSearch plugins or removed
ZooKeeper configuration	✗	Not applicable to OpenSearch
Custom request handlers	✗	Only /select endpoint is translated; custom handlers need manual migration
UpdateProcessorChain	✗	Recreate equivalent logic using OpenSearch ingest pipelines
DIH (Data Import Handler)	✗	Replace with an external indexing pipeline

For the full list of supported query types and known limitations, see Running the Transform Proxy.

Pre-migration checklist

• Verify versions: Confirm source and target versions are in the compatibility matrix above
• Determine source version: Run curl <source-endpoint>/ and note the version string
• Identify unsupported components: Review the "Not supported" table and plan manual migration for those items
• Plan index scope: Decide which indexes to migrate; use index allowlists to exclude system indexes or test with a subset first
• Test with subset: Configure an index allowlist with 1-2 representative indexes and run a test migration
• Check for multi-type indexes (ES 6.x): If migrating from ES 6.x, identify indexes with multiple mapping types

Next steps

Once you've verified your migration path is supported:

1. Deploying to Kubernetes or Deploying to EKS - Deploy Migration Assistant
2. Workflow CLI Overview - Learn about the migration workflow approach
3. Workflow CLI Getting Started - Run your first migration