Skip to content

Commit f2c329a

Browse files
rrelledgerrelledge
authored
RS: Add GET shards and migrate shards REST API references (#380)
* DOC-3850 RS: Add GET shards and migrate shards REST API references * Fix boolean case for JSON examples * Fix case of UIDs * DOC-3850 Add redis_info example for shard response * DOC-3850 Feedback update to add GET shards connected_clients REST API example response * DOC-3850 Feedback update to add migrate shards REST API use cases and more info about dry_run * DOC-3850 Feedback update to add impact of shard migration * DOC-4062 Add /bdbs/uid/shards reference * DOC-3850 Create separate shard migration article and crosslink with rladmin & REST API references
1 parent f3404c7 commit f2c329a

File tree

9 files changed

+577
-15
lines changed

9 files changed

+577
-15
lines changed

‎content/operate/rs/databases/migrate-shards.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
alwaysopen: false
3+
categories:
4+
- docs
5+
- operate
6+
- rs
7+
db_type: database
8+
description: How to migrate database shards to other nodes in a Redis Software cluster.
9+
linkTitle: Migrate shards
10+
title: Migrate database shards
11+
toc: 'true'
12+
weight: 32
13+
---
14+
15+
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">}}).
16+
17+
## Use cases for shard migration
18+
19+
Migrate database shards to a different node in the following scenarios:
20+
21+
- Before node removal.
22+
23+
- To balance the database manually in case of latency issues or uneven load distribution across nodes.
24+
25+
- To manage node resources, such as memory usage.
26+
27+
## Considerations for shard migration
28+
29+
For databases with replication:
30+
31+
- Migrating a shard will not cause disruptions since a primary shard will still be available.
32+
33+
- 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.
34+
35+
For databases without replication, the migrated shard will not be available until the migration is done.
36+
37+
Connected clients shouldn't be disconnected in either case.
38+
39+
If too many primary shards are placed on the same node, it can impact database performance.
40+
41+
## Migrate specific shard
42+
43+
To migrate a specific database shard, use one of the following methods:
44+
45+
- [`rladmin migrate shard`]({{<relref "/operate/rs/references/cli-utilities/rladmin/migrate#migrate-shard">}}):
46+
47+
```sh
48+
rladmin migrate shard <shard_id> target_node <node_id>
49+
```
50+
51+
- [Migrate shard]({{<relref "/operate/rs/references/rest-api/requests/shards/actions/migrate#post-shard">}}) REST API request:
52+
53+
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.
54+
55+
```sh
56+
POST /v1/shards/<shard_id>/actions/migrate
57+
{
58+
"target_node_uid": <node_id>
59+
}
60+
```
61+
62+
Example JSON response body:
63+
64+
```json
65+
{
66+
"action_uid": "<action_id>",
67+
"description": "Migrate was triggered"
68+
}
69+
```
70+
71+
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.
72+
73+
## Migrate multiple shards
74+
75+
To migrate multiple database shards, use one of the following methods:
76+
77+
- [`rladmin migrate shard`]({{<relref "/operate/rs/references/cli-utilities/rladmin/migrate#migrate-shard">}}):
78+
79+
```sh
80+
rladmin migrate shard <shard_id1> <shard_id2> <shard_id3> target_node <node_id>
81+
```
82+
83+
- [Migrate multiple shards]({{<relref "/operate/rs/references/rest-api/requests/shards/actions/migrate#post-multi-shards">}}) REST API request:
84+
85+
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.
86+
87+
```sh
88+
POST /v1/shards/actions/migrate
89+
{
90+
"shard_uids": ["<shard_id1>","<shard_id2>","<shard_id3>"],
91+
"target_node_uid": <node_id>
92+
}
93+
```
94+
95+
Example JSON response body:
96+
97+
```json
98+
{
99+
"action_uid": "<action_id>",
100+
"description": "Migrate was triggered"
101+
}
102+
```
103+
104+
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.
105+
106+
## Migrate all shards from a node
107+
108+
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">}}):
109+
110+
```sh
111+
rladmin migrate node <origin_node_id> all_shards target_node <node_id>
112+
```
113+
114+
## Migrate primary shards
115+
116+
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.
117+
118+
To migrate a specific database's primary shards:
119+
120+
```sh
121+
rladmin migrate db db:<id> all_master_shards target_node <node_id>
122+
```
123+
124+
To migrate all primary shards from a specific node:
125+
126+
```sh
127+
rladmin migrate node <origin_node_id> all_master_shards target_node <node_id>
128+
```
129+
130+
## Migrate replica shards
131+
132+
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.
133+
134+
To migrate a specific database's replica shards:
135+
136+
```sh
137+
rladmin migrate db db:<id> all_slave_shards target_node <node_id>
138+
```
139+
140+
To migrate all replica shards from a specific node:
141+
142+
```sh
143+
rladmin migrate node <origin_node_id> all_slave_shards target_node <node_id>
144+
```

‎content/operate/rs/references/cli-utilities/rladmin/migrate.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ weight: $weight
1515

1616
Moves Redis Enterprise shards or endpoints to a new node in the same cluster.
1717

18+
For more information about shard migration use cases and considerations, see [Migrate database shards]({{<relref "/operate/rs/databases/migrate-shards">}}).
19+
1820
## `migrate all_master_shards`
1921

2022
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‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Clusters, databases, nodes, and shards collect various statistics at regular tim
1717
- [Cluster stats]({{< relref "/operate/rs/references/rest-api/requests/cluster/stats" >}})
1818
- [Database stats]({{< relref "/operate/rs/references/rest-api/requests/bdbs/stats" >}})
1919
- [Node stats]({{< relref "/operate/rs/references/rest-api/requests/nodes/stats" >}})
20-
- [Shard stats]({{< relref "/operate/rs/references/rest-api/requests/shards-stats" >}})
20+
- [Shard stats]({{< relref "/operate/rs/references/rest-api/requests/shards/stats" >}})
2121

2222
View endpoint stats using `GET` requests, see:
2323
- [Endpoint stats]({{< relref "/operate/rs/references/rest-api/requests/endpoints-stats" >}})

‎content/operate/rs/references/rest-api/requests/bdbs/shards.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
Title: Database shards requests
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rs
8+
description: REST API requests for database shards
9+
headerRange: '[1-2]'
10+
linkTitle: shards
11+
weight: $weight
12+
---
13+
14+
| Method | Path | Description |
15+
|--------|------|-------------|
16+
| [GET](#get-bdb-shards) | `/v1/bdbs/{bdb_uid}/shards` | Get the status of a database's shards |
17+
18+
## Get database shards {#get-bdb-shards}
19+
20+
GET /v1/bdbs/{int: bdb_uid}/shards
21+
22+
Gets the status for all shards that belong to the specified database.
23+
24+
### Request {#get-request}
25+
26+
#### Example HTTP request
27+
28+
GET /bdbs/1/shards?extra_info_keys=used_memory_rss&extra_info_keys=connected_clients
29+
30+
#### Request headers
31+
32+
| Key | Value | Description |
33+
|-----|-------|-------------|
34+
| Host | cnm.cluster.fqdn | Domain name |
35+
| Accept | application/json | Accepted media type |
36+
37+
#### URL parameters
38+
39+
| Field | Type | Description |
40+
|-------|------|-------------|
41+
| bdb_uid | integer | The unique ID of the database. |
42+
43+
### Response {#get-response}
44+
45+
The response body contains a JSON array with all shards, represented as [shard objects]({{<relref "/operate/rs/references/rest-api/objects/shard">}}).
46+
47+
#### Example JSON body
48+
49+
```json
50+
[
51+
{
52+
"uid": "1",
53+
"role": "master",
54+
"assigned_slots": "0-8191",
55+
"bdb_uid": 1,
56+
"detailed_status": "ok",
57+
"loading": {
58+
"status": "idle"
59+
},
60+
"node_uid": "1",
61+
"redis_info": {
62+
"connected_clients": 14,
63+
"used_memory_rss": 12460032
64+
},
65+
"report_timestamp": "2024-09-13T15:28:10Z",
66+
"status": "active"
67+
},
68+
{
69+
"uid": 2,
70+
"role": "slave",
71+
// additional fields...
72+
}
73+
]
74+
```
75+
76+
### Status codes {#get-status-codes}
77+
78+
| Code | Description |
79+
|------|-------------|
80+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. |
81+
| [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‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
Title: Shard requests
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rs
8+
description: REST API requests for database shards
9+
headerRange: '[1-2]'
10+
hideListLinks: true
11+
linkTitle: shards
12+
weight: $weight
13+
---
14+
15+
| Method | Path | Description |
16+
|--------|------|-------------|
17+
| [GET](#get-all-shards) | `/v1/shards` | Get all shards |
18+
| [GET](#get-shard) | `/v1/shards/{uid}` | Get a specific shard |
19+
20+
## Get all shards {#get-all-shards}
21+
22+
GET /v1/shards
23+
24+
Get information about all shards in the cluster.
25+
26+
### Request {#get-all-request}
27+
28+
#### Example HTTP request
29+
30+
GET /shards?extra_info_keys=used_memory_rss&extra_info_keys=connected_clients
31+
32+
#### Request headers
33+
34+
| Key | Value | Description |
35+
|-----|-------|-------------|
36+
| Host | cnm.cluster.fqdn | Domain name |
37+
| Accept | application/json | Accepted media type |
38+
39+
#### Query parameters
40+
41+
| Field | Type | Description |
42+
|-------|------|-------------|
43+
| extra_info_keys | list of strings | A list of extra keys to be fetched (optional) |
44+
45+
### Response {#get-all-response}
46+
47+
Returns a JSON array of [shard objects]({{<relref "/operate/rs/references/rest-api/objects/shard">}}).
48+
49+
#### Example JSON body
50+
51+
```json
52+
[
53+
{
54+
"uid": "1",
55+
"role": "master",
56+
"assigned_slots": "0-16383",
57+
"bdb_uid": 1,
58+
"detailed_status": "ok",
59+
"loading": {
60+
"status": "idle"
61+
},
62+
"node_uid": "1",
63+
"redis_info": {
64+
"connected_clients": 14,
65+
"used_memory_rss": 12263424
66+
},
67+
"report_timestamp": "2024-06-28T18:44:01Z",
68+
"status": "active"
69+
},
70+
{
71+
"uid": 2,
72+
"role": "slave",
73+
// additional fields...
74+
}
75+
]
76+
```
77+
78+
### Status codes {#get-all-status-codes}
79+
80+
| Code | Description |
81+
|------|-------------|
82+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. |
83+
84+
## Get shard {#get-shard}
85+
86+
GET /v1/shards/{int: uid}
87+
88+
Gets information about a single shard.
89+
90+
### Request {#get-request}
91+
92+
#### Example HTTP request
93+
94+
GET /shards/1?extra_info_keys=used_memory_rss&extra_info_keys=connected_clients
95+
96+
#### Request headers
97+
98+
| Key | Value | Description |
99+
|-----|-------|-------------|
100+
| Host | cnm.cluster.fqdn | Domain name |
101+
| Accept | application/json | Accepted media type |
102+
103+
#### URL parameters
104+
105+
| Field | Type | Description |
106+
|-------|------|-------------|
107+
| uid | integer | The unique ID of the requested shard. |
108+
109+
#### Query parameters
110+
111+
| Field | Type | Description |
112+
|-------|------|-------------|
113+
| extra_info_keys | list of strings | A list of extra keys to be fetched (optional) |
114+
115+
### Response {#get-response}
116+
117+
Returns a [shard object]({{<relref "/operate/rs/references/rest-api/objects/shard">}}).
118+
119+
#### Example JSON body
120+
121+
```json
122+
{
123+
"assigned_slots": "0-16383",
124+
"bdb_uid": 1,
125+
"detailed_status": "ok",
126+
"loading": {
127+
"status": "idle"
128+
},
129+
"node_uid": "1",
130+
"redis_info": {
131+
"connected_clients": 14,
132+
"used_memory_rss": 12263424
133+
},
134+
"role": "master",
135+
"report_timestamp": "2024-06-28T18:44:01Z",
136+
"status": "active",
137+
"uid": "1"
138+
}
139+
```
140+
141+
### Status codes {#get-status-codes}
142+
143+
| Code | Description |
144+
|------|-------------|
145+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. |
146+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Shard UID does not exist. |

0 commit comments

Comments
 (0)