RS: Add GET shards and migrate shards REST API references

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`]({{<relref "/operate/rs/references/cli-utilities/rladmin/migrate">}}) command or [REST API requests]({{<relref "/operate/rs/references/rest-api/requests/shards/actions/migrate">}}).
+
+## 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`]({{<relref "/operate/rs/references/cli-utilities/rladmin/migrate#migrate-shard">}}):
+
+    ```sh
+    rladmin migrate shard <shard_id> target_node <node_id>
+    ```
+
+- [Migrate shard]({{<relref "/operate/rs/references/rest-api/requests/shards/actions/migrate#post-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]({{<relref "/operate/rs/references/rest-api/requests/shards/actions/migrate#post-request-body">}}) for more options.
+
+    ```sh
+    POST /v1/shards/<shard_id>/actions/migrate
+    {
+        "target_node_uid": <node_id>
+    }
+    ```
+
+    Example JSON response body:
+
+    ```json
+    {
+        "action_uid": "<action_id>",
+        "description": "Migrate was triggered"
+    }
+    ```
+
+    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.
+
+## Migrate multiple shards
+
+To migrate multiple database shards, use one of the following methods:
+
+- [`rladmin migrate shard`]({{<relref "/operate/rs/references/cli-utilities/rladmin/migrate#migrate-shard">}}):
+
+    ```sh
+    rladmin migrate shard <shard_id1> <shard_id2> <shard_id3> target_node <node_id>
+    ```
+
+- [Migrate multiple shards]({{<relref "/operate/rs/references/rest-api/requests/shards/actions/migrate#post-multi-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]({{<relref "/operate/rs/references/rest-api/requests/shards/actions/migrate#post-multi-request-body">}}) for more options.
+
+    ```sh
+    POST /v1/shards/actions/migrate
+    {
+        "shard_uids": ["<shard_id1>","<shard_id2>","<shard_id3>"],
+        "target_node_uid": <node_id>
+    }
+    ```
+
+    Example JSON response body:
+
+    ```json
+    {
+        "action_uid": "<action_id>",
+        "description": "Migrate was triggered"
+    }
+    ```
+
+    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.
+
+## Migrate all shards from a node
+
+To migrate all shards from a specific node to another node, run [`rladmin migrate all_shards`]({{<relref "/operate/rs/references/cli-utilities/rladmin/migrate#migrate-all_shards">}}):
+
+```sh
+rladmin migrate node <origin_node_id> all_shards target_node <node_id>
+```
+
+## Migrate primary shards
+
+You can use the [`rladmin migrate all_master_shards`]({{<relref "/operate/rs/references/cli-utilities/rladmin/migrate#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:<id> all_master_shards target_node <node_id>
+```
+
+To migrate all primary shards from a specific node:
+
+```sh
+rladmin migrate node <origin_node_id> all_master_shards target_node <node_id>
+```
+
+## Migrate replica shards
+
+You can use the [`rladmin migrate all_slave_shards`]({{<relref "/operate/rs/references/cli-utilities/rladmin/migrate#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:<id> all_slave_shards target_node <node_id>
+```
+
+To migrate all replica shards from a specific node:
+
+```sh
+rladmin migrate node <origin_node_id> all_slave_shards target_node <node_id>
+```

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]({{<relref "/operate/rs/databases/migrate-shards">}}).
+
 ## `migrate all_master_shards`
 
 Moves all primary shards of a specified database or node to a new node in the same cluster.

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
 

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]({{<relref "/operate/rs/references/rest-api/objects/shard">}}).
+
+#### 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. |

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]({{<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": {
+			"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]({{<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": {
+		"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. |