Skip to content

Document --max-shard-size-bytes support for shards larger than 80 GiB #12204

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sumobrian wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document --max-shard-size-bytes support for shards larger than 80 GiB #12204

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion _migration-assistant/is-migration-assistant-right-for-you.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ To use `Reindex-from-Snapshot` (RFS), ensure the following:
- If you choose to bring your own snapshot (that is, one not created by Migration Assistant), the following settings must be applied when creating the snapshot:
- `include_global_state: true` – Ensures that global cluster state is included.
- `compress: false` – Disables metadata compression, which is required for compatibility with RFS.
- Shards of up to **80 GiB** are supported by default. Larger shard sizes can be configured, **except in AWS GovCloud (US)**, where 80 GiB is the maximum.
- Shards of up to **80 GiB** are supported by default. Larger shard sizes can be configured. For details, see [Configuring large shard support]({{site.url}}{{site.baseurl}}/migration-assistant/migration-phases/deploy/configuration-options/#configuring-large-shard-support). **In AWS GovCloud (US) with the ECS deployment**, 80 GiB is the maximum supported shard size.
- In OpenSearch 2.9 and later, snapshots of indexes that use the zstd or zstd_no_dict codecs are not supported. If you need to migrate these indexes using `Reindex-from-Snapshot`, you must first reindex them on the source cluster using either `default` or `best_compression` before creating a new snapshot for use with RFS.

### Capture and Replay
Expand Down
8 changes: 8 additions & 0 deletions _migration-assistant/migration-phases/backfill.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,14 @@ Migration Assistant creates an Amazon CloudWatch dashboard, named `MigrationAssi

You can find the backfill dashboard in the CloudWatch console based on the AWS Region in which you have deployed Migration Assistant. The metric graphs for your target cluster will be blank until you select the OpenSearch domain you're migrating to from the dropdown menu at the top of the dashboard.

## Troubleshooting

Use the following guidance to troubleshoot common backfill issues.

### Shards appear stuck with no errors

If `console backfill status --deep-check` shows shards that remain in progress indefinitely with no errors in the logs, the shard may exceed the default **80 GiB** size limit. Shards larger than this limit are skipped by RFS workers without surfacing an error in the backfill status output. To resolve this, increase the `--max-shard-size-bytes` value in your deployment configuration. For details, see [Configuring large shard support]({{site.url}}{{site.baseurl}}/migration-assistant/migration-phases/deploy/configuration-options/#configuring-large-shard-support).

## Validating the backfill

After the backfill is complete and the workers have stopped, examine the contents of your cluster using the [Refresh API]({{site.url}}{{site.baseurl}}/api-reference/index-apis/refresh/) and the [Flush API]({{site.url}}{{site.baseurl}}/api-reference/index-apis/flush/). The following example uses the console CLI with the Refresh API to check the backfill status:
Expand Down
11 changes: 11 additions & 0 deletions _migration-assistant/migration-phases/deploy/configuration-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,17 @@ The RFS configuration uses the following options. All options are optional.

To view all available arguments for `reindexFromSnapshotExtraArgs`, see [Snapshot migrations README](https://github.com/opensearch-project/opensearch-migrations/blob/main/DocumentsFromSnapshotMigration/README.md#arguments). At a minimum, no extra arguments may be needed.

### Configuring large shard support

By default, RFS supports shards of up to **80 GiB**. To migrate larger shards, pass the `--max-shard-size-bytes` flag through `reindexFromSnapshotExtraArgs`. For example, to support shards up to 200 GiB:

```json
"reindexFromSnapshotExtraArgs": "--max-shard-size-bytes 214748364800"
```
{% include copy.html %}

Ensure that your worker nodes have sufficient local disk space, because RFS requires approximately **2x the shard size** in local storage to unpack and process the Lucene index. For more information about available RFS arguments, see the [DocumentsFromSnapshotMigration README](https://github.com/opensearch-project/opensearch-migrations/blob/main/DocumentsFromSnapshotMigration/README.md#arguments).

Copy link
Copy Markdown
Contributor

@jugal-chauhan jugal-chauhan Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we are missing a {% include copy.html %} block here

## Live capture migration with C&R

The following sample CDK performs a live capture migration with C&R:
Expand Down
Loading
⚡