Migrate metadata
Metadata migration moves the target cluster into a shape that can accept the incoming data and traffic. It processes mappings, templates, aliases, and other index-level definitions before document backfill or replay becomes meaningful.
In the workflow model, metadata migration is a configured phase inside the migration workflow.
Metadata workflow steps
When metadataMigrationConfig is present, the workflow runs two logical steps:
evaluateMetadatamigrateMetadata
The first step evaluates what would be applied. The second step writes those changes to the target. If approvals are enabled, the workflow can pause between these steps so you can inspect the result before continuing.
Metadata migration scope
Metadata migration can process:
- Index settings
- Index mappings
- Legacy and composable templates
- Component templates
- Aliases
It does not automatically migrate everything around the cluster. Plan separate work for security configuration, ISM or ILM policies, ingest pipelines, dashboards or Kibana objects, and other environment-specific assets.
Built-in transformations
The current metadata migration path already includes built-in transformations for several common compatibility issues, including:
stringtotextandkeywordflattenedtoflat_objectdense_vectortoknn_vector- Additional vector compatibility transformations for newer OpenSearch and Serverless targets.
If your migration needs more than the built-ins, you can also supply custom metadata transformers through transformerConfig, transformerConfigBase64, or transformerConfigFile.
Important configuration fields
Useful metadata settings include:
indexAllowlistindexTemplateAllowlistcomponentTemplateAllowlistmultiTypeBehaviorallowLooseVersionMatchingtransformerConfig*
Use the version-matched sample from your console to see the exact structure for your installed release. (Version-matched means the schema corresponds to the Migration Assistant version installed in your console pod—workflow configure sample --load reads the schema from /root/.workflowUser.schema.json on that pod, so the loaded sample always has the fields that release supports.) To load and edit the sample, run the following commands:
workflow configure sample --load
workflow configure edit
Index filtering behavior
The metadata indexAllowlist is evaluated after the snapshot has already been taken. It supports:
- Exact index names
- Regex patterns prefixed with
regex:
This is different from the snapshot creation allow list, which uses the source cluster’s own snapshot multi-index expression syntax.
Multi-type behavior
If your migration involves older Elasticsearch data sets with multi-type mappings, set multiTypeBehavior intentionally:
NONEto fail when multi-type data is encountered.UNIONto merge types into one mappingSPLITto route types into separate indexes.
Do not guess here. Pilot it first on a small subset if multi-type behavior matters to your application.
Validate metadata before continuing
After metadata migration runs, verify the target before moving to full backfill or cutover:
console clusters curl target /_cat/indices?v
console clusters curl target /_cat/templates?v
console clusters curl target /_cat/aliases?v
console clusters curl target /my-index/_mapping
Monitor and troubleshoot
Use the workflow tools rather than raw pod paths whenever possible:
workflow manage
workflow status
workflow log all
If metadata migration fails, the usual causes are:
- Incompatible mappings or settings
- Missing transformations
- Unsupported target-side features
- Authentication or connectivity issues to the target.
Previous phase
The previous phase depends on your migration scenario:
- Scenario 1: Backfill only: Deploy
- Scenario 2: Live capture only: Reroute traffic from the source to the Capture Proxy
Next phase
The next phase depends on your migration scenario:
- Scenario 1: Backfill only: Backfill
- Scenario 2: Live capture only: Replay captured traffic
For a complete overview of all migration phases, see Migration phases.