Skip to content

Commit 1d31f13

Browse files
rrelledgerrelledge
committed
DOC-4191 RS: Add rebalance database shards REST API reference
1 parent c77a10a commit 1d31f13

File tree

2 files changed

+141
-0
lines changed

2 files changed

+141
-0
lines changed

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,12 @@ weight: $weight
3838
|--------|------|-------------|
3939
| [GET]({{< relref "./optimize_shards_placement#get-bdbs-actions-optimize-shards-placement" >}}) | `/v1/bdbs/{uid}/actions/optimize_shards_placement` | Get optimized shards placement for a database |
4040

41+
## Rebalance
42+
43+
| Method | Path | Description |
44+
|--------|------|-------------|
45+
| [PUT]({{<relref "/operate/rs/references/rest-api/requests/bdbs/actions/rebalance#put-bdbs-actions-rebalance">}}) | `/v1/bdbs/{uid}/actions/rebalance` | Rebalance database shards |
46+
4147
## Recover
4248

4349
| Method | Path | Description |

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

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
Title: Rebalance database requests
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rs
8+
description: REST API requests to rebalance database shards
9+
headerRange: '[1-2]'
10+
linkTitle: rebalance
11+
weight: $weight
12+
---
13+
14+
| Method | Path | Description |
15+
|--------|------|-------------|
16+
| [PUT](#put-bdbs-actions-rebalance) | `/v1/bdbs/{uid}/actions/rebalance` | Rebalance database shards |
17+
18+
## Rebalance database shards {#put-bdbs-actions-rebalance}
19+
20+
```sh
21+
PUT /v1/bdbs/{int: uid}/actions/rebalance
22+
```
23+
24+
Distributes the database's shards across nodes based on the database's shard placement policy. See [Shard placement policy]({{<relref "/operate/rs/databases/memory-performance/shard-placement-policy">}}) for more information about shard placement and available policies.
25+
26+
#### Required permissions
27+
28+
| Permission name | Roles |
29+
|-----------------|-------|
30+
| [view_bdb_info]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_info" >}}) | admin<br />cluster_member<br />cluster_viewer<br />db_member<br />db_viewer |
31+
32+
### Request {#put-request}
33+
34+
#### Example HTTP request
35+
36+
```sh
37+
PUT /bdbs/1/actions/rebalance
38+
```
39+
40+
Dry-run example:
41+
42+
```sh
43+
PUT /bdbs/1/actions/rebalance?only_failovers=true&dry_run=true
44+
```
45+
46+
#### URL parameters
47+
48+
| Field | Type | Description |
49+
|-------|------|-------------|
50+
| uid | integer | The unique ID of the database to rebalance. |
51+
52+
#### Query parameters
53+
54+
| Field | Type | Description |
55+
|-------|------|-------------|
56+
| dry_run | boolean | If true, returns the blueprint of the rebalanced database without actually changing the database. Default is false. |
57+
| only_failovers | boolean | If true, only runs failovers and no migrations. Default is false. |
58+
| max_operations | integer | Optional. The number of operations to do. Only works if `only_failovers` is true. If not provided, uses the number of the database's primary-replica pairs. |
59+
60+
### Response {#put-response}
61+
62+
- If `dry_run` is `false`, returns 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.
63+
64+
- If `dry_run` is `true`, returns the balanced shards' blueprint.
65+
66+
You can rearrange shards according to this blueprint if you use it in the `shards_blueprint` field of a [rearrange database shards]({{<relref "/operate/rs/references/rest-api/requests/bdbs/actions/optimize_shards_placement#put-bdbs-rearrange-shards">}}) request.
67+
68+
You should also pass the rebalance shards' `cluster-state-id` response header as a request header of the rearrange database shards request to make sure the optimized shard placement is relevant for the current cluster state. The cluster will reject the update if its state changed since the optimal shards placement blueprint was generated.
69+
70+
#### Example response
71+
72+
If `dry_run` is `false`:
73+
74+
```sh
75+
{
76+
"action_uid": "21ad01d5-55aa-4ec6-b5c0-44dc95176486"
77+
}
78+
```
79+
80+
If `dry_run` is `true`:
81+
82+
```sh
83+
[
84+
{
85+
"nodes": [
86+
{
87+
"node_uid": "3",
88+
"role": "master"
89+
},
90+
{
91+
"node_uid": "1",
92+
"role": "slave"
93+
}
94+
],
95+
"slot_range": "5461-10922"
96+
},
97+
{
98+
"nodes": [
99+
{
100+
"node_uid": "3",
101+
"role": "master"
102+
},
103+
{
104+
"node_uid": "1",
105+
"role": "slave"
106+
}
107+
],
108+
"slot_range": "10923-16383"
109+
},
110+
{
111+
"nodes": [
112+
{
113+
"node_uid": "3",
114+
"role": "master"
115+
},
116+
{
117+
"node_uid": "1",
118+
"role": "slave"
119+
}
120+
],
121+
"slot_range": "0-5460"
122+
}
123+
]
124+
```
125+
126+
#### Status codes {#put-status-codes}
127+
128+
| Code | Description |
129+
|------|-------------|
130+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | When `dry_run` is false: The request is accepted and is being processed. When the database is recovered, its status will become active.<br />When `dry_run` is true: No error. |
131+
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad request. Invalid input parameters. |
132+
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to perform an action on a nonexistent database. |
133+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Not enough resources in the cluster to host the database. |
134+
| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Database is currently busy with another action, recovery is already in progress, or is not in a recoverable state. |
135+
| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Internal server error. |

0 commit comments

Comments
 (0)