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

Playbook: Apache Solr 8.x or 9.x → OpenSearch 3.x

This playbook assumes Migration Assistant is already deployed on Kubernetes or Amazon Elastic Kubernetes Service (Amazon EKS). To learn how to deploy Migration Assistant, see Choose your deployment. The playbook describes the end-to-end process for migrating from Apache Solr 8.x or 9.x to OpenSearch 3.x using snapshot-based document backfill.

The example commands and configuration snippets target SolrCloud 8.11 against OpenSearch 3.x, but the same workflow applies to standalone Solr and to Solr 6.x–9.x—only the version string changes (for example, SOLR 8.11.0 or SOLR 9.7.0).

Solr migrations support backfill only—Capture and Replay is not supported for Solr sources. If your application requires continuous writes during migration, pause writes to the source cluster for the duration of the backfill.

Solr migration architecture

Solr migrations differ from Elasticsearch migrations because Solr uses a different HTTP API, schema format (schema.xml), and query syntax. Migration Assistant uses a specialized component called SolrReader to read Solr backup data (Lucene segment files), translate schema.xml field types to OpenSearch mappings, and bulk-index documents. For more information, see Solr migration overview.

If your target is Amazon OpenSearch Serverless, this playbook still applies. The only differences are the target endpoint, the authConfig.sigv4.service value (aoss instead of es), and a one-time data access policy configuration. For the Serverless-specific target configuration, see Migrate to OpenSearch Serverless.

Step 1: Create a Solr backup

Migration Assistant reads from Solr’s native backup format. Use Solr’s backup API for both SolrCloud and standalone. Do not copy data files from a running Solr installation because segment merges or pending commits can corrupt the resulting backup.

For SolrCloud, the backup target must be a shared file system mounted at the same path on every node, or an S3BackupRepository. For cluster-wide constraints, see Apache Solr—SolrCloud backup/restore requirements.

Alternatively, you can configure Solr to write backups directly to Amazon Simple Storage Service (Amazon S3) using S3BackupRepository, which eliminates the need for a shared filesystem. For this approach, see the Solr backfill guide.

SolrCloud

To create a backup in SolrCloud, run the following command:

curl "http://<SOLR_HOST>:<SOLR_PORT>/solr/admin/collections?action=BACKUP&name=my-backup&collection=<COLLECTION>&location=/path/to/shared-backup"

To check the backup status, poll the request status API until it reports completed:

curl "http://<SOLR_HOST>:<SOLR_PORT>/solr/admin/collections?action=REQUESTSTATUS&requestid=<REQUEST_ID>"

Standalone Solr

For standalone Solr, use the replication handler to create a backup:

curl "http://<SOLR_HOST>:<SOLR_PORT>/solr/<CORE>/replication?command=backup&name=my-backup&location=/path/to/backup"

To verify that the backup completed, query the replication details and confirm that details.backup.status returns success:

curl "http://<SOLR_HOST>:<SOLR_PORT>/solr/<CORE>/replication?command=details"

If you used a local file system instead of S3BackupRepository, upload the resulting backup to S3 so Migration Assistant can read it:

aws s3 sync /path/to/backup/ s3://<BUCKET>/solr-backup/

Step 2: Configure the workflow

Connect to the Migration Console and load the sample configuration:

kubectl exec -it migration-console-0 -n ma -- /bin/bash
workflow configure sample --load
workflow configure edit

Set the source as your Solr backup location and the target as your OpenSearch 3.5 cluster. The schema translation (Solr field types → OpenSearch mappings) is handled automatically by SolrReader.

Sample workflow configuration

The following example shows a workflow configuration for migrating a Solr source to OpenSearch:

{
  "sourceClusters": {
    "solr-source": {
      "endpoint": "http://<SOLR_HOST>:<SOLR_PORT>",
      "allowInsecure": true,
      "version": "SOLR 8.11.4",
      "snapshotInfo": {
        "repos": {
          "default-s3": {
            "awsRegion": "<REGION>",
            "s3RepoPathUri": "s3://<BUCKET>/solr-backup"
          }
        },
        "snapshots": {
          "solr-migration-snapshot": {
            "config": { "createSnapshotConfig": {} },
            "repoName": "default-s3"
          }
        }
      }
    }
  },
  "targetClusters": {
    "target": {
      "endpoint": "https://<OPENSEARCH_HOST>:9200",
      "allowInsecure": true,
      "authConfig": {
        "basic": { "secretName": "target-creds" }
      }
    }
  },
  "snapshotMigrationConfigs": [
    {
      "fromSource": "solr-source",
      "toTarget": "target",
      "perSnapshotConfig": {
        "solr-migration-snapshot": [
          {
            "metadataMigrationConfig": {
              "skipEvaluateApproval": true,
              "skipMigrateApproval": true
            },
            "documentBackfillConfig": {
              "podReplicas": 4
            }
          }
        ]
      }
    }
  ]
}

Always verify field names against workflow configure sample for your installed version.

Step 3: Submit and monitor the workflow

Submit the workflow and open the monitoring interface:

workflow submit
workflow manage    # Interactive TUI (Terminal User Interface)

The workflow performs the following steps:

1. Reads the Solr backup data.
2. Translates schema.xml field types to OpenSearch mappings.
3. Bulk-indexes documents into the target.

Step 4: Verify the migration

Run the following commands to verify document counts and query results:

# Check document counts on target
console clusters cat-indices

# Verify a specific collection
console clusters curl target /<collection>/_count

# Test a query
console clusters curl target /<collection>/_search --json '{"query":{"match_all":{}},"size":5}'

Schema translation reference

SolrReader automatically translates the following Solr field types.

Troubleshooting

If you encounter issues, see Troubleshooting. To isolate problems, start with a single collection before migrating all data.

Related documentation

For more information, see the following resources:

• Solr migration overview
• Solr backfill guide – Step-by-step Amazon S3 backup configuration and workflow configuration for Solr.
• Supported migration paths