diff --git a/content/operate/rs/databases/migrate-shards.md b/content/operate/rs/databases/migrate-shards.md new file mode 100644 index 0000000000..12469ffb99 --- /dev/null +++ b/content/operate/rs/databases/migrate-shards.md @@ -0,0 +1,144 @@ +--- +alwaysopen: false +categories: +- docs +- operate +- rs +db_type: database +description: How to migrate database shards to other nodes in a Redis Software cluster. +linkTitle: Migrate shards +title: Migrate database shards +toc: 'true' +weight: 32 +--- + +To migrate database shards to other nodes in the cluster, you can use the [`rladmin migrate`]({{}}) command or [REST API requests]({{}}). + +## Use cases for shard migration + +Migrate database shards to a different node in the following scenarios: + +- Before node removal. + +- To balance the database manually in case of latency issues or uneven load distribution across nodes. + +- To manage node resources, such as memory usage. + +## Considerations for shard migration + +For databases with replication: + +- Migrating a shard will not cause disruptions since a primary shard will still be available. + +- If you try to migrate a primary shard, it will be demoted to a replica shard and a replica shard will be promoted to primary before the migration. If you set `"preserve_roles": true` in the request, a second failover will occur after the migration finishes to change the migrated shard's role back to primary. + +For databases without replication, the migrated shard will not be available until the migration is done. + +Connected clients shouldn't be disconnected in either case. + +If too many primary shards are placed on the same node, it can impact database performance. + +## Migrate specific shard + +To migrate a specific database shard, use one of the following methods: + +- [`rladmin migrate shard`]({{}}): + + ```sh + rladmin migrate shard target_node + ``` + +- [Migrate shard]({{}}) REST API request: + + Specify the ID of the shard to migrate in the request path and the destination node's ID as the `target_node_uid` in the request body. See the [request reference]({{}}) for more options. + + ```sh + POST /v1/shards//actions/migrate + { + "target_node_uid": + } + ``` + + Example JSON response body: + + ```json + { + "action_uid": "", + "description": "Migrate was triggered" + } + ``` + + You can track the action's progress with a [`GET /v1/actions/`]({{}}) request. + +## Migrate multiple shards + +To migrate multiple database shards, use one of the following methods: + +- [`rladmin migrate shard`]({{}}): + + ```sh + rladmin migrate shard target_node + ``` + +- [Migrate multiple shards]({{}}) REST API request: + + Specify the IDs of the shards to migrate in the `shard_uids` list and the destination node's ID as the `target_node_uid` in the request body. See the [request reference]({{}}) for more options. + + ```sh + POST /v1/shards/actions/migrate + { + "shard_uids": ["","",""], + "target_node_uid": + } + ``` + + Example JSON response body: + + ```json + { + "action_uid": "", + "description": "Migrate was triggered" + } + ``` + + You can track the action's progress with a [`GET /v1/actions/`]({{}}) request. + +## Migrate all shards from a node + +To migrate all shards from a specific node to another node, run [`rladmin migrate all_shards`]({{}}): + +```sh +rladmin migrate node all_shards target_node +``` + +## Migrate primary shards + +You can use the [`rladmin migrate all_master_shards`]({{}}) command to migrate all primary shards for a specific database or node to another node in the cluster. + +To migrate a specific database's primary shards: + +```sh +rladmin migrate db db: all_master_shards target_node +``` + +To migrate all primary shards from a specific node: + +```sh +rladmin migrate node all_master_shards target_node +``` + +## Migrate replica shards + +You can use the [`rladmin migrate all_slave_shards`]({{}}) command to migrate all replica shards for a specific database or node to another node in the cluster. + +To migrate a specific database's replica shards: + +```sh +rladmin migrate db db: all_slave_shards target_node +``` + +To migrate all replica shards from a specific node: + +```sh +rladmin migrate node all_slave_shards target_node +``` diff --git a/content/operate/rs/references/cli-utilities/rladmin/migrate.md b/content/operate/rs/references/cli-utilities/rladmin/migrate.md index 913b5334e4..dc33ea3532 100644 --- a/content/operate/rs/references/cli-utilities/rladmin/migrate.md +++ b/content/operate/rs/references/cli-utilities/rladmin/migrate.md @@ -15,6 +15,8 @@ weight: $weight Moves Redis Enterprise shards or endpoints to a new node in the same cluster. +For more information about shard migration use cases and considerations, see [Migrate database shards]({{}}). + ## `migrate all_master_shards` Moves all primary shards of a specified database or node to a new node in the same cluster. diff --git a/content/operate/rs/references/rest-api/objects/statistics/_index.md b/content/operate/rs/references/rest-api/objects/statistics/_index.md index 2b3ae4d65f..f8f04f026a 100644 --- a/content/operate/rs/references/rest-api/objects/statistics/_index.md +++ b/content/operate/rs/references/rest-api/objects/statistics/_index.md @@ -17,7 +17,7 @@ Clusters, databases, nodes, and shards collect various statistics at regular tim - [Cluster stats]({{< relref "/operate/rs/references/rest-api/requests/cluster/stats" >}}) - [Database stats]({{< relref "/operate/rs/references/rest-api/requests/bdbs/stats" >}}) - [Node stats]({{< relref "/operate/rs/references/rest-api/requests/nodes/stats" >}}) -- [Shard stats]({{< relref "/operate/rs/references/rest-api/requests/shards-stats" >}}) +- [Shard stats]({{< relref "/operate/rs/references/rest-api/requests/shards/stats" >}}) ### Response object diff --git a/content/operate/rs/references/rest-api/requests/bdbs/shards.md b/content/operate/rs/references/rest-api/requests/bdbs/shards.md new file mode 100644 index 0000000000..4ea6207cb6 --- /dev/null +++ b/content/operate/rs/references/rest-api/requests/bdbs/shards.md @@ -0,0 +1,81 @@ +--- +Title: Database shards requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: REST API requests for database shards +headerRange: '[1-2]' +linkTitle: shards +weight: $weight +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-bdb-shards) | `/v1/bdbs/{bdb_uid}/shards` | Get the status of a database's shards | + +## Get database shards {#get-bdb-shards} + + GET /v1/bdbs/{int: bdb_uid}/shards + +Gets the status for all shards that belong to the specified database. + +### Request {#get-request} + +#### Example HTTP request + + GET /bdbs/1/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 | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| bdb_uid | integer | The unique ID of the database. | + +### Response {#get-response} + +The response body contains a JSON array with all shards, represented as [shard objects]({{}}). + +#### Example JSON body + +```json +[ + { + "uid": "1", + "role": "master", + "assigned_slots": "0-8191", + "bdb_uid": 1, + "detailed_status": "ok", + "loading": { + "status": "idle" + }, + "node_uid": "1", + "redis_info": { + "connected_clients": 14, + "used_memory_rss": 12460032 + }, + "report_timestamp": "2024-09-13T15:28:10Z", + "status": "active" + }, + { + "uid": 2, + "role": "slave", + // additional fields... + } +] +``` + +### 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) | bdb uid does not exist. | diff --git a/content/operate/rs/references/rest-api/requests/shards/_index.md b/content/operate/rs/references/rest-api/requests/shards/_index.md new file mode 100644 index 0000000000..7801b65838 --- /dev/null +++ b/content/operate/rs/references/rest-api/requests/shards/_index.md @@ -0,0 +1,146 @@ +--- +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]({{}}). + +#### 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": { + "connected_clients": 14, + "used_memory_rss": 12263424 + }, + "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]({{}}). + +#### Example JSON body + +```json +{ + "assigned_slots": "0-16383", + "bdb_uid": 1, + "detailed_status": "ok", + "loading": { + "status": "idle" + }, + "node_uid": "1", + "redis_info": { + "connected_clients": 14, + "used_memory_rss": 12263424 + }, + "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. | diff --git a/content/operate/rs/references/rest-api/requests/shards/actions/_index.md b/content/operate/rs/references/rest-api/requests/shards/actions/_index.md new file mode 100644 index 0000000000..4550f9395f --- /dev/null +++ b/content/operate/rs/references/rest-api/requests/shards/actions/_index.md @@ -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]({{}}) | `/v1/shards/actions/migrate` | Migrate multiple shards | +| [POST]({{}}) | `/v1/shards/{uid}/actions/migrate` | Migrate a specific shard | diff --git a/content/operate/rs/references/rest-api/requests/shards/actions/migrate.md b/content/operate/rs/references/rest-api/requests/shards/actions/migrate.md new file mode 100644 index 0000000000..7c535291da --- /dev/null +++ b/content/operate/rs/references/rest-api/requests/shards/actions/migrate.md @@ -0,0 +1,169 @@ +--- +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. + +For more information about shard migration use cases and considerations, see [Migrate database shards]({{}}). + +#### Required permissions + +| Permission name | Roles | +|-----------------|-------| +| [migrate_shard]({{< relref "/operate/rs/references/rest-api/permissions#migrate_shard" >}}) | admin
cluster_member
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 {#post-multi-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. If the dry run succeeds, the request returns a `200 OK` status code. Otherwise, it returns a JSON object with an error code and description. | +| 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/`]({{}}) 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. + +For more information about shard migration use cases and considerations, see [Migrate database shards]({{}}). + +#### Required permissions + +| Permission name | Roles | +|-----------------|-------| +| [migrate_shard]({{< relref "/operate/rs/references/rest-api/permissions#migrate_shard" >}}) | admin
cluster_member
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 {#post-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. If the dry run succeeds, the request returns a `200 OK` status code. Otherwise, it returns a JSON object with an error code and description. | +| 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/`]({{}}) 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. | diff --git a/content/operate/rs/references/rest-api/requests/shards-stats/_index.md b/content/operate/rs/references/rest-api/requests/shards/stats/_index.md similarity index 91% rename from content/operate/rs/references/rest-api/requests/shards-stats/_index.md rename to content/operate/rs/references/rest-api/requests/shards/stats/_index.md index e9f8ddfa79..f81b8e690e 100644 --- a/content/operate/rs/references/rest-api/requests/shards-stats/_index.md +++ b/content/operate/rs/references/rest-api/requests/shards/stats/_index.md @@ -8,8 +8,9 @@ categories: description: Shard statistics requests headerRange: '[1-2]' hideListLinks: true -linkTitle: shards/stats +linkTitle: stats weight: $weight +aliases: /operate/rs/references/rest-api/requests/shards-stats/ --- | Method | Path | Description | @@ -132,8 +133,8 @@ Returns a JSON array of [statistics]({{< relref "/operate/rs/references/rest-api | Code | Description | |------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | -| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | No shards exist | +| [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) | No shards exist | ## Get shard stats {#get-shard-stats} @@ -231,12 +232,10 @@ Returns [statistics]({{< relref "/operate/rs/references/rest-api/objects/statist } ``` - - ### Status codes {#get-status-codes} | Code | Description | |------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | -| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Shard does not exist | -| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Shard isn't currently active | +| [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 | +| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Shard isn't currently active | diff --git a/content/operate/rs/references/rest-api/requests/shards-stats/last.md b/content/operate/rs/references/rest-api/requests/shards/stats/last.md similarity index 89% rename from content/operate/rs/references/rest-api/requests/shards-stats/last.md rename to content/operate/rs/references/rest-api/requests/shards/stats/last.md index 96c890c815..133c53d3cb 100644 --- a/content/operate/rs/references/rest-api/requests/shards-stats/last.md +++ b/content/operate/rs/references/rest-api/requests/shards/stats/last.md @@ -9,6 +9,7 @@ description: Most recent shard statistics requests headerRange: '[1-2]' linkTitle: last weight: $weight +aliases: /operate/rs/references/rest-api/requests/shards-stats/last/ --- | Method | Path | Description | @@ -101,8 +102,8 @@ Returns most recent [statistics]({{< relref "/operate/rs/references/rest-api/obj | Code | Description | |------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | -| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | No shards exist | +| [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) | No shards exist | ## Get latest shard stats {#get-shard-stats-last} @@ -186,10 +187,10 @@ Returns the most recent [statistics]({{< relref "/operate/rs/references/rest-api } ``` -### Status codes {#get-all-status-codes} +### Status codes {#get-status-codes} | Code | Description | |------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | -| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Shard does not exist | -| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Shard isn't currently active | +| [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 | +| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Shard isn't currently active |