-
Notifications
You must be signed in to change notification settings - Fork 269
RS: Add GET shards and migrate shards REST API references #380
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.
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
Merged
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
d44c5ce
DOC-3850 RS: Add GET shards and migrate shards REST API references
rrelledge d9af3d8
Fix boolean case for JSON examples
rrelledge 9be48c8
Fix case of UIDs
rrelledge 70f40c3
DOC-3850 Add redis_info example for shard response
rrelledge cd26da4
DOC-3850 Feedback update to add GET shards connected_clients REST API…
rrelledge 5ac9ebe
DOC-3850 Feedback update to add migrate shards REST API use cases and…
rrelledge f450bf5
DOC-3850 Feedback update to add impact of shard migration
rrelledge 8ad3655
DOC-4062 Add /bdbs/uid/shards reference
rrelledge 7662b41
DOC-3850 Create separate shard migration article and crosslink with r…
rrelledge File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
140 changes: 140 additions & 0 deletions
140
content/operate/rs/references/rest-api/requests/shards/_index.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,140 @@ | ||
| --- | ||
| Title: Shard requests | ||
| alwaysopen: false | ||
| categories: | ||
| - docs | ||
| - operate | ||
| - rs | ||
| description: REST API requests for database shards | ||
| headerRange: '[1-2]' | ||
| hideListLinks: true | ||
| linkTitle: shards | ||
| weight: $weight | ||
| --- | ||
|
|
||
| | Method | Path | Description | | ||
| |--------|------|-------------| | ||
| | [GET](#get-all-shards) | `/v1/shards` | Get all shards | | ||
| | [GET](#get-shard) | `/v1/shards/{uid}` | Get a specific shard | | ||
|
|
||
| ## Get all shards {#get-all-shards} | ||
|
|
||
| GET /v1/shards | ||
|
|
||
| Get information about all shards in the cluster. | ||
|
|
||
| ### Request {#get-all-request} | ||
|
|
||
| #### Example HTTP request | ||
|
|
||
| GET /shards?extra_info_keys=used_memory_rss&extra_info_keys=connected_clients | ||
|
|
||
| #### Request headers | ||
|
|
||
| | Key | Value | Description | | ||
| |-----|-------|-------------| | ||
| | Host | cnm.cluster.fqdn | Domain name | | ||
| | Accept | application/json | Accepted media type | | ||
|
|
||
| #### Query parameters | ||
|
|
||
| | Field | Type | Description | | ||
| |-------|------|-------------| | ||
| | extra_info_keys | list of strings | A list of extra keys to be fetched (optional) | | ||
|
|
||
| ### Response {#get-all-response} | ||
|
|
||
| Returns a JSON array of [shard objects]({{<relref "/operate/rs/references/rest-api/objects/shard">}}). | ||
|
|
||
| #### Example JSON body | ||
|
|
||
| ```json | ||
| [ | ||
| { | ||
| "uid": "1", | ||
| "role": "master", | ||
| "assigned_slots": "0-16383", | ||
| "bdb_uid": 1, | ||
| "detailed_status": "ok", | ||
| "loading": { | ||
| "status": "idle" | ||
| }, | ||
| "node_uid": "1", | ||
| "redis_info": {}, | ||
| "report_timestamp": "2024-06-28T18:44:01Z", | ||
| "status": "active" | ||
| }, | ||
| { | ||
| "uid": 2, | ||
| "role": "slave", | ||
| // additional fields... | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| ### Status codes {#get-all-status-codes} | ||
|
|
||
| | Code | Description | | ||
| |------|-------------| | ||
| | [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. | | ||
|
|
||
| ## Get shard {#get-shard} | ||
|
|
||
| GET /v1/shards/{int: uid} | ||
|
|
||
| Gets information about a single shard. | ||
|
|
||
| ### Request {#get-request} | ||
|
|
||
| #### Example HTTP request | ||
|
|
||
| GET /shards/1?extra_info_keys=used_memory_rss&extra_info_keys=connected_clients | ||
|
|
||
| #### Request headers | ||
|
|
||
| | Key | Value | Description | | ||
| |-----|-------|-------------| | ||
| | Host | cnm.cluster.fqdn | Domain name | | ||
| | Accept | application/json | Accepted media type | | ||
|
|
||
| #### URL parameters | ||
|
|
||
| | Field | Type | Description | | ||
| |-------|------|-------------| | ||
| | uid | integer | The unique ID of the requested shard. | | ||
|
|
||
| #### Query parameters | ||
|
|
||
| | Field | Type | Description | | ||
| |-------|------|-------------| | ||
| | extra_info_keys | list of strings | A list of extra keys to be fetched (optional) | | ||
|
|
||
| ### Response {#get-response} | ||
|
|
||
| Returns a [shard object]({{<relref "/operate/rs/references/rest-api/objects/shard">}}). | ||
|
|
||
| #### Example JSON body | ||
|
|
||
| ```json | ||
| { | ||
| "assigned_slots": "0-16383", | ||
| "bdb_uid": 1, | ||
| "detailed_status": "ok", | ||
| "loading": { | ||
| "status": "idle" | ||
| }, | ||
| "node_uid": "1", | ||
| "redis_info": {}, | ||
| "role": "master", | ||
| "report_timestamp": "2024-06-28T18:44:01Z", | ||
| "status": "active", | ||
| "uid": "1" | ||
| } | ||
| ``` | ||
|
|
||
| ### Status codes {#get-status-codes} | ||
|
|
||
| | Code | Description | | ||
| |------|-------------| | ||
| | [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. | | ||
| | [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Shard UID does not exist. | |
20 changes: 20 additions & 0 deletions
20
content/operate/rs/references/rest-api/requests/shards/actions/_index.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| --- | ||
| Title: Shard actions requests | ||
| alwaysopen: false | ||
| categories: | ||
| - docs | ||
| - operate | ||
| - rs | ||
| description: REST API requests to perform shard actions | ||
| headerRange: '[1-2]' | ||
| hideListLinks: true | ||
| linkTitle: actions | ||
| weight: $weight | ||
| --- | ||
|
|
||
| ## Migrate | ||
|
|
||
| | Method | Path | Description | | ||
| |--------|------|-------------| | ||
| | [POST]({{<relref "/operate/rs/references/rest-api/requests/shards/actions/migrate#post-multi-shards">}}) | `/v1/shards/actions/migrate` | Migrate multiple shards | | ||
| | [POST]({{<relref "/operate/rs/references/rest-api/requests/shards/actions/migrate#post-shard">}}) | `/v1/shards/{uid}/actions/migrate` | Migrate a specific shard | |
165 changes: 165 additions & 0 deletions
165
content/operate/rs/references/rest-api/requests/shards/actions/migrate.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,165 @@ | ||
| --- | ||
| Title: Migrate shards requests | ||
| alwaysopen: false | ||
| categories: | ||
| - docs | ||
| - operate | ||
| - rs | ||
| description: REST API requests to migrate database shards | ||
| headerRange: '[1-2]' | ||
| linkTitle: migrate | ||
| weight: $weight | ||
| --- | ||
|
|
||
| | Method | Path | Description | | ||
| |--------|------|-------------| | ||
| | [POST](#post-multi-shards) | `/v1/shards/actions/migrate` | Migrate multiple shards | | ||
| | [POST](#post-shard) | `/v1/shards/{uid}/actions/migrate` | Migrate a specific shard | | ||
|
|
||
| ## Migrate multiple shards {#post-multi-shards} | ||
|
|
||
| POST /v1/shards/actions/migrate | ||
|
|
||
| Migrates the list of given shard UIDs to the node specified by `target_node_uid`. The shards can be from multiple databases. This request is asynchronous. | ||
|
|
||
| #### Required permissions | ||
|
|
||
| | Permission name | Roles | | ||
| |-----------------|-------| | ||
| | [migrate_shard]({{< relref "/operate/rs/references/rest-api/permissions#migrate_shard" >}}) | admin<br />cluster_member<br />db_member | | ||
|
|
||
| ### Request {#post-multi-request} | ||
|
|
||
| #### Example HTTP request | ||
|
|
||
| POST /shards/actions/migrate | ||
|
|
||
| #### Example JSON body | ||
|
|
||
| ```json | ||
| { | ||
| "shard_uids": ["2","4","6"], | ||
| "target_node_uid": 9, | ||
| "override_rack_policy": false, | ||
| "preserve_roles": false, | ||
| "max_concurrent_bdb_migrations": 3 | ||
| } | ||
| ``` | ||
|
|
||
| #### Request headers | ||
|
|
||
| | Key | Value | Description | | ||
| |-----|-------|-------------| | ||
| | Host | cnm.cluster.fqdn | Domain name | | ||
| | Accept | application/json | Accepted media type | | ||
|
|
||
| #### Request body | ||
|
|
||
| The request body is a JSON object that can contain the following fields: | ||
|
|
||
| | Field | Type | Description | | ||
| |-------|------|-------------| | ||
| | shard_uids | array of strings | List of shard UIDs to migrate. | | ||
| | target_node_uid | integer | UID of the node to where the shards should migrate. | | ||
| | override_rack_policy | boolean | If true, overrides and ignores rack-aware policy violations. | | ||
| | dry_run | boolean | Determines whether the migration is actually done. If true, will just do a dry-run. | | ||
| | preserve_roles | boolean | If true, preserves the migrated shards' roles after migration. | | ||
| | max_concurrent_bdb_migrations | integer | The number of concurrent databases that can migrate shards. | | ||
|
|
||
| ### Response {#post-multi-response} | ||
|
|
||
| Returns a JSON object with an `action_uid`. You can track the action's progress with a [`GET /v1/actions/<action_uid>`]({{<relref "/operate/rs/references/rest-api/requests/actions#get-action">}}) request. | ||
|
|
||
| #### Example JSON body | ||
|
|
||
| ```json | ||
| { | ||
| "action_uid": "e5e24ddf-a456-4a7e-ad53-4463cd44880e", | ||
| "description": "Migrate was triggered" | ||
| } | ||
| ``` | ||
|
|
||
| ### Status codes {#post-multi-status-codes} | ||
|
|
||
| | Code | Description | | ||
| |------|-------------| | ||
| | [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. | | ||
| | [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Conflicting parameters. | | ||
| | [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | A list of shard uids is required and not given, a specified shard does not exist, or a node UID is required and not given. | | ||
| | [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Migration failed. | | ||
|
|
||
|
|
||
| ## Migrate shard {#post-shard} | ||
|
|
||
| POST /v1/shards/{int: uid}/actions/migrate | ||
|
|
||
| Migrates the shard with the given `shard_uid` to the node specified by `target_node_uid`. If the shard is already on the target node, nothing happens. This request is asynchronous. | ||
|
|
||
| #### Required permissions | ||
|
|
||
| | Permission name | Roles | | ||
| |-----------------|-------| | ||
| | [migrate_shard]({{< relref "/operate/rs/references/rest-api/permissions#migrate_shard" >}}) | admin<br />cluster_member<br />db_member | | ||
|
|
||
| ### Request {#post-request} | ||
|
|
||
| #### Example HTTP request | ||
|
|
||
| POST /shards/1/actions/migrate | ||
|
|
||
| #### Example JSON body | ||
|
|
||
| ```json | ||
| { | ||
| "target_node_uid": 9, | ||
| "override_rack_policy": false, | ||
| "preserve_roles": false | ||
| } | ||
| ``` | ||
|
|
||
| #### Request headers | ||
|
|
||
| | Key | Value | Description | | ||
| |-----|-------|-------------| | ||
| | Host | cnm.cluster.fqdn | Domain name | | ||
| | Accept | application/json | Accepted media type | | ||
|
|
||
|
|
||
| #### URL parameters | ||
|
|
||
| | Field | Type | Description | | ||
| |-------|------|-------------| | ||
| | uid | integer | The unique ID of the shard to migrate. | | ||
|
|
||
|
|
||
| #### Request body | ||
|
|
||
| The request body is a JSON object that can contain the following fields: | ||
|
|
||
| | Field | Type | Description | | ||
| |-------|------|-------------| | ||
| | target_node_uid | integer | UID of the node to where the shard should migrate. | | ||
| | override_rack_policy | boolean | If true, overrides and ignores rack-aware policy violations. | | ||
| | dry_run | boolean | Determines whether the migration is actually done. If true, will just do a dry-run. | | ||
| | preserve_roles | boolean | If true, preserves the migrated shards' roles after migration. | | ||
|
|
||
| ### Response {#post-response} | ||
|
|
||
| Returns a JSON object with an `action_uid`. You can track the action's progress with a [`GET /v1/actions/<action_uid>`]({{<relref "/operate/rs/references/rest-api/requests/actions#get-action">}}) request. | ||
|
|
||
| #### Example JSON body | ||
|
|
||
| ```json | ||
| { | ||
| "action_uid": "e5e24ddf-a456-4a7e-ad53-4463cd44880e", | ||
| "description": "Migrate was triggered" | ||
| } | ||
| ``` | ||
|
|
||
| ### Status codes {#post-status-codes} | ||
|
|
||
| | Code | Description | | ||
| |------|-------------| | ||
| | [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. | | ||
| | [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Shard does not exist, or node UID is required and not given. | | ||
| | [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Database is currently busy. | | ||
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
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.