You're viewing the current version of Migration Assistant documentation (Kubernetes/EKS-based). For the classic ECS/CDK-based version, see the classic documentation.

Migrate to OpenSearch Serverless

If your target is an Amazon OpenSearch Serverless collection, Serverless works as a target for every source Migration Assistant supports: Elasticsearch 1.x–2.x, OpenSearch 1.x–2.x, Amazon OpenSearch Service, and Apache Solr 6.x–9.x (backfill only). The migration steps are the same as for any other OpenSearch target. Follow your source’s playbook and use the Serverless-specific target configuration from this page.

Collection types

Amazon OpenSearch Serverless supports the following collection types. Migration Assistant auto-detects the collection type and adjusts behavior accordingly.

If your source data relies on specific document IDs (for example, for lookups or deduplication), use a SEARCH collection.

When migrating to a VECTORSEARCH collection, knn_vector field mappings are automatically converted to Faiss HNSW for Serverless compatibility, and model_id references are removed (Serverless does not support training APIs).

Connecting your collection to Migration Assistant

Migration Assistant requires the following configuration to access your OpenSearch Serverless collection:

1. The migration IAM role must have aoss:APIAccessAll in its IAM policy (the Amazon Elastic Kubernetes Service (EKS) deployment handles this automatically).
2. The migration IAM role must be listed as a Principal in your collection’s data access policy (you must configure this).

Step 1: Find the migration role ARN

The EKS deployment creates a role named <eks-cluster-name>-migrations-role. To find the role, run the following command:

aws iam list-roles --query "Roles[?contains(RoleName,'migrations-role')].{Name:RoleName,Arn:Arn}" --output table

Step 2: Update your collection’s data access policy

Add the migration role as a principal in your collection’s data access policy. The role needs both collection-level and index-level permissions.

Run the following command in the AWS CLI:

aws opensearchserverless create-access-policy \
  --name migration-access \
  --type data \
  --policy '[{
    "Rules": [
      {
        "ResourceType": "collection",
        "Resource": ["collection/<COLLECTION-NAME>"],
        "Permission": [
          "aoss:CreateCollectionItems",
          "aoss:DeleteCollectionItems",
          "aoss:UpdateCollectionItems",
          "aoss:DescribeCollectionItems"
        ]
      },
      {
        "ResourceType": "index",
        "Resource": ["index/<COLLECTION-NAME>/*"],
        "Permission": [
          "aoss:CreateIndex",
          "aoss:DeleteIndex",
          "aoss:UpdateIndex",
          "aoss:DescribeIndex",
          "aoss:ReadDocument",
          "aoss:WriteDocument"
        ]
      }
    ],
    "Principal": ["<MIGRATION-ROLE-ARN>"]
  }]'

Replace <COLLECTION-NAME> with your collection name and <MIGRATION-ROLE-ARN> with the ARN from Step 1.

If your collection already has a data access policy, use update-access-policy instead to add the migration role to the existing Principal list. See Data access control for Amazon OpenSearch Serverless for details.

Step 3: Configure the workflow

Configure your OpenSearch Serverless collection as the target in your workflow configuration. The key difference from a managed OpenSearch Service target is service: aoss (instead of service: es):

workflow configure edit

Set the target cluster:

{
  "targetClusters": {
    "target": {
      "endpoint": "https://<collection-id>.<region>.aoss.amazonaws.com",
      "authConfig": {
        "sigv4": {
          "region": "<region>",
          "service": "aoss"
        }
      }
    }
  }
}

Then follow the steps in Using the Workflow CLI.

Per-source playbooks

Choose the playbook for your source type:

• Self-managed/third-party Elasticsearch or OpenSearch – Follow the Elasticsearch 6.8 → OpenSearch 3.5 playbook, then replace the target cluster block with the preceding OpenSearch Serverless configuration.
• Amazon OpenSearch Service/legacy Elasticsearch Service – Follow the Amazon OpenSearch Service → Amazon OpenSearch Serverless playbook.
• Apache Solr – Follow the Apache Solr 8.11 → OpenSearch 3.5 playbook, then replace the target cluster block with the preceding OpenSearch Serverless configuration.