Enhanced the documentation for the convert_index_to_remote ISM action with comprehensive details and examples: #11491 #11495
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add detailed description of searchable snapshot conversion process - Document three optional parameters: include_aliases, ignore_index_settings, number_of_replicas - Add Prerequisites and Usage notes sections - Include three examples: basic, advanced configuration, and complete policy - Provide guidance on automatic deletion, repository matching, and replica considerations Signed-off-by: Seung Yeon Joo <[email protected]>
…entation Enhance convert_index_to_remote documentation with comprehensive details
wntmddus
requested review from
AMoo-Miki,
dlvenable,
epugh,
kolchfa-aws,
natebower and
sumobrian
as code owners
|
Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Editorial review -> Merged. Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer. When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference). The doc reviewer will arrange for an editorial review. |
This was referenced Nov 5, 2025
Collaborator
|
@vikasvb90 Could you review this PR? |
linuxpi
approved these changes
Nov 21, 2025
kolchfa-aws
reviewed
Nov 21, 2025
Collaborator
kolchfa-aws
left a comment
kolchfa-aws
left a comment
There was a problem hiding this comment.
Thank you, @wntmddus! Please see my comments and let me know if you have any questions.
| ### convert_index_to_remote | ||
|
|
||
| Converts an index from a local snapshot repository to a remote repository. | ||
| Converts an index to a searchable snapshot by restoring it from a remote snapshot repository. This action is useful for reducing storage costs by moving infrequently accessed data to remote storage while keeping it searchable. The action performs a restore operation from the specified snapshot and automatically deletes the original index once the restore is successfully accepted, ensuring only the remote index remains. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Converts an index to a searchable snapshot by restoring it from a remote snapshot repository. This action is useful for reducing storage costs by moving infrequently accessed data to remote storage while keeping it searchable. The action performs a restore operation from the specified snapshot and automatically deletes the original index once the restore is successfully accepted, ensuring only the remote index remains. | |
| Converts an existing index into a searchable snapshot by restoring it from a remote snapshot repository. This action reduces storage costs by moving infrequently accessed data to remote storage while keeping it searchable. After the restore request is accepted, the original index is automatically deleted, ensuring that only the remote snapshot-backed index remains. |
| :--- | :--- |:--- |:--- | | ||
| `repository` | The repository name registered through the native snapshot API operations. | String | Yes | N/A | ||
| `snapshot` | The snapshot name created through the snapshot action. | String | Yes | N/A | ||
| `repository` | The repository name registered through the native snapshot API operations. Must be a remote repository type (for example, S3, Azure, or GCS). | `string` | Yes | N/A |
Collaborator
There was a problem hiding this comment.
What are the actual valid values for this parameter? Is it s3, azure, and gcs? Please list them in code font.
Collaborator
There was a problem hiding this comment.
Please format data types without code font (so, "String", "Boolean", etc.)
| `repository` | The repository name registered through the native snapshot API operations. | String | Yes | N/A | ||
| `snapshot` | The snapshot name created through the snapshot action. | String | Yes | N/A | ||
| `repository` | The repository name registered through the native snapshot API operations. Must be a remote repository type (for example, S3, Azure, or GCS). | `string` | Yes | N/A | ||
| `snapshot` | The snapshot name created through the snapshot action. | `string` | Yes | N/A |
Collaborator
There was a problem hiding this comment.
Suggested change
| `snapshot` | The snapshot name created through the snapshot action. | `string` | Yes | N/A | |
| `snapshot` | The name of the snapshot created by the snapshot action. | String | Yes | N/A |
| `snapshot` | The snapshot name created through the snapshot action. | String | Yes | N/A | ||
| `repository` | The repository name registered through the native snapshot API operations. Must be a remote repository type (for example, S3, Azure, or GCS). | `string` | Yes | N/A | ||
| `snapshot` | The snapshot name created through the snapshot action. | `string` | Yes | N/A | ||
| `include_aliases` | Whether to include index aliases during the restore operation. When set to `true`, all aliases associated with the original index are restored along with the remote index. Set to `true` if your application references the index through aliases. | `boolean` | No | `false` |
Collaborator
There was a problem hiding this comment.
Suggested change
| `include_aliases` | Whether to include index aliases during the restore operation. When set to `true`, all aliases associated with the original index are restored along with the remote index. Set to `true` if your application references the index through aliases. | `boolean` | No | `false` | |
| `include_aliases` | Whether to include index aliases during the restore operation. If `true`, all aliases associated with the original index are restored with the remote index. If your application accesses the index using aliases, set this parameter to `true`. | Boolean | No | `false` |
| `repository` | The repository name registered through the native snapshot API operations. Must be a remote repository type (for example, S3, Azure, or GCS). | `string` | Yes | N/A | ||
| `snapshot` | The snapshot name created through the snapshot action. | `string` | Yes | N/A | ||
| `include_aliases` | Whether to include index aliases during the restore operation. When set to `true`, all aliases associated with the original index are restored along with the remote index. Set to `true` if your application references the index through aliases. | `boolean` | No | `false` | ||
| `ignore_index_settings` | A comma-separated list of index settings to ignore during the restore operation. For example, `"index.refresh_interval,index.number_of_replicas"`. This is useful when you want to apply different settings to the restored remote index than what was configured in the original index. | `string` | No | Empty string |
Collaborator
There was a problem hiding this comment.
Suggested change
| `ignore_index_settings` | A comma-separated list of index settings to ignore during the restore operation. For example, `"index.refresh_interval,index.number_of_replicas"`. This is useful when you want to apply different settings to the restored remote index than what was configured in the original index. | `string` | No | Empty string | |
| `ignore_index_settings` | A comma-separated list of index settings to ignore during the restore operation. For example, `index.refresh_interval,index.number_of_replicas`. This is useful when you want to apply different settings to the restored remote index than the ones configured in the original index. | String | No | Empty string |
| `snapshot` | The snapshot name created through the snapshot action. | `string` | Yes | N/A | ||
| `include_aliases` | Whether to include index aliases during the restore operation. When set to `true`, all aliases associated with the original index are restored along with the remote index. Set to `true` if your application references the index through aliases. | `boolean` | No | `false` | ||
| `ignore_index_settings` | A comma-separated list of index settings to ignore during the restore operation. For example, `"index.refresh_interval,index.number_of_replicas"`. This is useful when you want to apply different settings to the restored remote index than what was configured in the original index. | `string` | No | Empty string | ||
| `number_of_replicas` | The number of replicas to configure for the restored remote index. This allows you to control replica allocation during the conversion process without requiring a separate update operation. Setting this during conversion helps prevent cluster yellow state or unnecessary load from replica allocation. | `integer` | No | `0` |
Collaborator
There was a problem hiding this comment.
Suggested change
| `number_of_replicas` | The number of replicas to configure for the restored remote index. This allows you to control replica allocation during the conversion process without requiring a separate update operation. Setting this during conversion helps prevent cluster yellow state or unnecessary load from replica allocation. | `integer` | No | `0` | |
| `number_of_replicas` | The number of replicas to configure for the restored remote index. This allows you to control replica allocation during the conversion process without requiring a separate update operation. Setting `number_of_replicas` during conversion helps prevent the cluster from entering a yellow state or creating unnecessary load during replica assignment. | Integer | No | `0` |
|
|
||
| #### Usage notes | ||
|
|
||
| - **Automatic deletion**: The original index is automatically deleted after the remote snapshot restore is successfully accepted. This ensures that only the searchable snapshot version remains, completing the conversion process. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - **Automatic deletion**: The original index is automatically deleted after the remote snapshot restore is successfully accepted. This ensures that only the searchable snapshot version remains, completing the conversion process. | |
| Note the following to ensure a smooth and predictable conversion when restoring an index as a searchable snapshot: | |
| - The original index is automatically deleted after the remote snapshot restore is successfully accepted. This ensures that only the searchable snapshot version remains, completing the conversion process. |
| #### Usage notes | ||
|
|
||
| - **Automatic deletion**: The original index is automatically deleted after the remote snapshot restore is successfully accepted. This ensures that only the searchable snapshot version remains, completing the conversion process. | ||
| - **Repository matching**: The repository name used in the `convert_index_to_remote` operation must match the repository name specified during the snapshot action. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - **Repository matching**: The repository name used in the `convert_index_to_remote` operation must match the repository name specified during the snapshot action. | |
| - The repository name used in the `convert_index_to_remote` operation must match the repository name specified during the snapshot action. |
|
|
||
| - **Automatic deletion**: The original index is automatically deleted after the remote snapshot restore is successfully accepted. This ensures that only the searchable snapshot version remains, completing the conversion process. | ||
| - **Repository matching**: The repository name used in the `convert_index_to_remote` operation must match the repository name specified during the snapshot action. | ||
| - **Variable references**: You can reference the snapshot using Mustache variables like `{% raw %}{{ctx.index}}{% endraw %}` or `{% raw %}{{ctx.indexUuid}}{% endraw %}` for dynamic naming. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - **Variable references**: You can reference the snapshot using Mustache variables like `{% raw %}{{ctx.index}}{% endraw %}` or `{% raw %}{{ctx.indexUuid}}{% endraw %}` for dynamic naming. | |
| - You can reference the snapshot using Mustache variables like `{% raw %}{{ctx.index}}{% endraw %}` or `{% raw %}{{ctx.indexUuid}}{% endraw %}` for dynamic naming. |
| - **Automatic deletion**: The original index is automatically deleted after the remote snapshot restore is successfully accepted. This ensures that only the searchable snapshot version remains, completing the conversion process. | ||
| - **Repository matching**: The repository name used in the `convert_index_to_remote` operation must match the repository name specified during the snapshot action. | ||
| - **Variable references**: You can reference the snapshot using Mustache variables like `{% raw %}{{ctx.index}}{% endraw %}` or `{% raw %}{{ctx.indexUuid}}{% endraw %}` for dynamic naming. | ||
| - **Replica considerations**: Consider your cluster's capacity when setting `number_of_replicas`. If there aren't enough eligible nodes for replica restoration, the cluster may enter a yellow state. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - **Replica considerations**: Consider your cluster's capacity when setting `number_of_replicas`. If there aren't enough eligible nodes for replica restoration, the cluster may enter a yellow state. | |
| - Consider your cluster's capacity when setting `number_of_replicas`. If there aren't enough eligible nodes for replica restoration, the cluster may enter a yellow state. |
kolchfa-aws
added
Doc review
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Enhanced the documentation for the
convert_index_to_remoteISM action with comprehensive details and examples:include_aliases: Control whether to restore index aliases along with the indexignore_index_settings: Specify settings to ignore during restore for customized configurationnumber_of_replicas: Set replica count during conversion to prevent cluster yellow stateThe resolved documentation provides more explicit guidance for users implementing searchable snapshots with ISM policies.
Issues Resolved
Closes opensearch-project/index-management#1487, opensearch-project/index-management#808 (comment)
Version
All versions with ISM searchable snapshot support.
Frontend features
N/A - Documentation only change.
Checklist