Skip to content

Commit 94c7e3f

Browse files
dwdoughertydwdougherty
committed
DOC-5867: add new CLUSTER MIGRATION command page (etc)
1 parent 989cdef commit 94c7e3f

File tree

6 files changed

+236
-2
lines changed

6 files changed

+236
-2
lines changed

‎content/commands/client-list.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,9 +135,11 @@ b: the client is waiting in a blocking operation
135135
c: connection to be closed after writing entire reply
136136
d: a watched keys has been modified - EXEC will fail
137137
e: the client is excluded from the client eviction mechanism
138+
g: the client is responsible for migrating slots (atomic slot migration)
138139
i: the client is waiting for a VM I/O (deprecated)
139140
M: the client is a master
140141
N: no specific flag set
142+
o: the client is responsible for importing slots (atomic slot migration)
141143
O: the client is a client in MONITOR mode
142144
P: the client is a Pub/Sub subscriber
143145
r: the client is in readonly mode against a cluster node
@@ -148,7 +150,7 @@ x: the client is in a MULTI/EXEC context
148150
t: the client enabled keys tracking in order to perform client side caching
149151
T: the client will not touch the LRU/LFU of the keys it accesses
150152
R: the client tracking target client is invalid
151-
B: the client enabled broadcast tracking mode
153+
B: the client enabled broadcast tracking mode
152154
```
153155

154156
The file descriptor events can be:

‎content/commands/cluster-countkeysinslot.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ command only queries the local data set, so contacting a node
3434
that is not serving the specified hash slot will always result in a count of
3535
zero being returned.
3636

37+
**Note:** During atomic slot migration operations (available since Redis 8.4.0), keys being imported or trimmed may be filtered out from the results.
38+
3739
```
3840
> CLUSTER COUNTKEYSINSLOT 7000
3941
(integer) 50341

‎content/commands/cluster-getkeysinslot.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,8 @@ node to another. The way the rehashing is performed is exposed in the Redis
4444
Cluster specification, or in a more simple to digest form, as an appendix
4545
of the [`CLUSTER SETSLOT`]({{< relref "/commands/cluster-setslot" >}}) command documentation.
4646

47+
**Note:** During atomic slot migration operations (available since Redis 8.4.0), keys being imported or trimmed may be filtered out from the results.
48+
4749
```
4850
> CLUSTER GETKEYSINSLOT 7000 3
4951
1) "key_39015"

‎content/commands/cluster-info.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,16 @@ total_cluster_links_buffer_limit_exceeded:0
5858
* `cluster_stats_messages_received`: Number of messages received via the cluster node-to-node binary bus.
5959
* `total_cluster_links_buffer_limit_exceeded`: Accumulated count of cluster links freed due to exceeding the `cluster-link-sendbuf-limit` configuration.
6060

61+
The following atomic slot migration fields may be included in the reply (available since Redis 8.4.0):
62+
63+
* `cluster_slot_migration_active_tasks`: Number of in-progress ASM tasks. Currently, it will be 1 or 0.
64+
* `cluster_slot_migration_active_trim_running`: Number of active trim jobs in progress and scheduled.
65+
* `cluster_slot_migration_active_trim_current_job_keys`: Number of keys scheduled for deletion in the current trim job.
66+
* `cluster_slot_migration_active_trim_current_job_trimmed`: Number of keys already deleted in the current trim job.
67+
* `cluster_slot_migration_stats_active_trim_started`: Total number of trim jobs that have started since the process began.
68+
* `cluster_slot_migration_stats_active_trim_completed`: Total number of trim jobs completed since the process began.
69+
* `cluster_slot_migration_stats_active_trim_cancelled`: Total number of trim jobs cancelled since the process began.
70+
6171
The following message-related fields may be included in the reply if the value is not 0:
6272
Each message type includes statistics on the number of messages sent and received.
6373
Here are the explanation of these fields:

‎content/commands/cluster-migration.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
---
2+
acl_categories:
3+
- '@admin'
4+
- '@slow'
5+
- '@dangerous'
6+
arguments:
7+
- arguments:
8+
- arguments:
9+
- display_text: start-slot
10+
name: start-slot
11+
type: integer
12+
- display_text: end-slot
13+
name: end-slot
14+
type: integer
15+
multiple: true
16+
name: import
17+
token: IMPORT
18+
type: block
19+
- arguments:
20+
- display_text: task-id
21+
name: task-id
22+
token: ID
23+
type: string
24+
- display_text: all
25+
name: all
26+
token: ALL
27+
type: pure-token
28+
name: cancel
29+
token: CANCEL
30+
type: oneof
31+
- arguments:
32+
- display_text: task-id
33+
name: task-id
34+
optional: true
35+
token: ID
36+
type: string
37+
- display_text: all
38+
name: all
39+
optional: true
40+
token: ALL
41+
type: pure-token
42+
name: status
43+
token: STATUS
44+
type: block
45+
name: subcommand
46+
type: oneof
47+
arity: -4
48+
categories:
49+
- docs
50+
- develop
51+
- stack
52+
- oss
53+
- rs
54+
- rc
55+
- oss
56+
- kubernetes
57+
- clients
58+
command_flags:
59+
- admin
60+
- stale
61+
- no_async_loading
62+
complexity: O(N) where N is the total number of the slots between the start slot and
63+
end slot arguments.
64+
description: Start, monitor, and cancel atomic slot migration tasks.
65+
group: cluster
66+
hidden: false
67+
linkTitle: CLUSTER MIGRATION
68+
since: 8.4.0
69+
summary: Start, monitor, and cancel atomic slot migration tasks.
70+
syntax_fmt: "CLUSTER MIGRATION <IMPORT\_start-slot end-slot [start-slot end-slot\n\
71+
\ ...] | CANCEL\_<ID\_task-id | ALL> | STATUS\_[ID\_task-id] [ALL]>"
72+
syntax_str: ''
73+
title: CLUSTER MIGRATION
74+
---
75+
76+
The `CLUSTER MIGRATION` command provides atomic slot migration functionality for Redis Cluster. This command allows you to import slots from other nodes, monitor the progress of migration tasks, and cancel ongoing migrations.
77+
78+
## Required arguments
79+
80+
<details open><summary><code>subcommand</code></summary>
81+
82+
The subcommand specifies the operation to perform:
83+
84+
- `IMPORT <start-slot> <end-slot> [<start-slot> <end-slot> ...]`: Executes on the destination master. Accepts multiple slot ranges and triggers atomic migration for the specified ranges. Returns a task ID that can be used to monitor the status of the task.
85+
86+
- `CANCEL [ID <task-id> | ALL]`: Cancels an ongoing migration task by its ID or cancels all tasks if `ALL` is specified. Note: Cancelling a task on the source node does not stop the migration on the destination node, which will continue retrying until it is also cancelled there.
87+
88+
- `STATUS [ID <task-id> | ALL]`: Displays the status of current and completed atomic slot migration tasks. If a specific task ID is provided, it returns detailed information for that task only. If no arguments are provided, returns status for all tasks.
89+
90+
</details>
91+
92+
## Examples
93+
94+
Import slots 0-1000 and 2000-3000 to the current node:
95+
96+
```bash
97+
CLUSTER MIGRATION IMPORT 0 1000 2000 3000
98+
```
99+
100+
Check the status of all migration tasks:
101+
102+
```bash
103+
CLUSTER MIGRATION STATUS ALL
104+
```
105+
106+
Check the status of a specific migration task:
107+
108+
```bash
109+
CLUSTER MIGRATION STATUS ID 24cf41718b20f7f05901743dffc40bc9b15db339
110+
```
111+
112+
Cancel a specific migration task:
113+
114+
```bash
115+
CLUSTER MIGRATION CANCEL ID 24cf41718b20f7f05901743dffc40bc9b15db339
116+
```
117+
118+
Cancel all migration tasks:
119+
120+
```bash
121+
CLUSTER MIGRATION CANCEL ALL
122+
```
123+
124+
## Return information
125+
126+
{{< multitabs id="return-info"
127+
tab1="RESP2"
128+
tab2="RESP3" >}}
129+
130+
For the `IMPORT` subcommand:
131+
[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): task ID on success, or error message on failure.
132+
133+
For the `CANCEL` subcommand:
134+
[Integer reply](../../develop/reference/protocol-spec#integers): number of cancelled tasks.
135+
136+
For the `STATUS` subcommand:
137+
[Array reply](../../develop/reference/protocol-spec#arrays): a list of migration task details. Each task is represented as an array containing field-value pairs:
138+
- `id`: Task identifier
139+
- `slots`: Slot range being migrated
140+
- `source`: Source node ID
141+
- `dest`: Destination node ID
142+
- `operation`: Operation type (typically "migrate")
143+
- `state`: Current state ("completed", "in_progress", etc.)
144+
- `last_error`: Last error message (empty if none)
145+
- `retries`: Number of retry attempts
146+
- `create_time`: Task creation timestamp
147+
- `start_time`: Task start timestamp
148+
- `end_time`: Task completion timestamp (if completed)
149+
- `write_pause_ms`: Write pause duration in milliseconds
150+
151+
-tab-sep-
152+
153+
For the `IMPORT` subcommand:
154+
[Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): task ID on success, or error message on failure.
155+
156+
For the `CANCEL` subcommand:
157+
[Integer reply](../../develop/reference/protocol-spec#integers): number of cancelled tasks.
158+
159+
For the `STATUS` subcommand:
160+
[Array reply](../../develop/reference/protocol-spec#arrays): a list of migration task details. Each task is represented as an array containing field-value pairs:
161+
- `id`: Task identifier
162+
- `slots`: Slot range being migrated
163+
- `source`: Source node ID
164+
- `dest`: Destination node ID
165+
- `operation`: Operation type (typically "migrate")
166+
- `state`: Current state ("completed", "in_progress", etc.)
167+
- `last_error`: Last error message (empty if none)
168+
- `retries`: Number of retry attempts
169+
- `create_time`: Task creation timestamp
170+
- `start_time`: Task start timestamp
171+
- `end_time`: Task completion timestamp (if completed)
172+
- `write_pause_ms`: Write pause duration in milliseconds
173+
174+
{{< /multitabs >}}
175+
176+
## Notes
177+
178+
- The atomic slot migration feature is available starting from Redis 8.4.0.
179+
- Migration tasks are tracked in memory and the number of archived tasks is controlled by the `cluster-slot-migration-max-archived-tasks` configuration (default: 32).
180+
- During migration, the source node may pause writes briefly to hand off slot ownership. The duration is controlled by `cluster-slot-migration-write-pause-timeout` (default: 10 seconds).
181+
- The handoff threshold is controlled by `cluster-slot-migration-handoff-max-lag-bytes` (default: 1MB).
182+
- Cancelling a task on the source node does not automatically stop the migration on the destination node.
183+
- In `CLUSTER MIGRATION STATUS` output, the "state" field will show `completed` for successful operations.
184+
- Tasks with empty "last_error" fields indicate no errors occurred during the migration process.
185+
186+
## Key visibility during migration
187+
188+
During atomic slot migration operations, certain keys may be filtered out from the following commands while importing or trimming is in progress:
189+
190+
- [`KEYS`]({{< relref "/commands/keys" >}})
191+
- [`SCAN`]({{< relref "/commands/scan" >}})
192+
- [`RANDOMKEY`]({{< relref "/commands/randomkey" >}})
193+
- [`CLUSTER GETKEYSINSLOT`]({{< relref "/commands/cluster-getkeysinslot" >}})
194+
- [`DBSIZE`]({{< relref "/commands/dbsize" >}})
195+
- [`CLUSTER COUNTKEYSINSLOT`]({{< relref "/commands/cluster-countkeysinslot" >}})
196+
197+
The [`INFO KEYSPACE`]({{< relref "/commands/info" >}}) command will continue to reflect the actual number of keys, including those being migrated.
198+
199+
## Related configuration
200+
201+
- `cluster-slot-migration-max-archived-tasks`: Maximum number of archived ASM tasks kept in memory for `CLUSTER MIGRATION STATUS ALL` output (default: 32, hidden config)
202+
- `cluster-slot-migration-handoff-max-lag-bytes`: After slot snapshot completion, if remaining replication stream size falls below this threshold, the source node pauses writes to hand off slot ownership. Higher values trigger handoff earlier but may cause longer write pauses. Lower values result in shorter write pauses but may be harder to reach with steady incoming writes (default: 1MB)
203+
- `cluster-slot-migration-write-pause-timeout`: Maximum duration that the source node pauses writes during ASM handoff. If the destination fails to take over slots within this timeout, the source assumes migration failed and resumes writes (default: 10 seconds)
204+
- `cluster-slot-migration-sync-buffer-drain-timeout`: Timeout for sync buffer drainage during ASM. Uses the maximum of this configurable timeout and a dynamic timeout based on slot snapshot application time (multiplied by 2 for conservatism) to handle cases where synchronization gap remains above acceptable limits (default: 60 seconds, hidden config)
205+
206+
## RDB format changes
207+
208+
A new auxiliary field `cluster-asm-task` has been added to the RDB format to support atomic slot migration. When an import operation begins, the master propagates an internal command through the replication stream, allowing replicas to recognize that an ASM operation is in progress. This enables replicas to trigger relevant module events so that modules can adapt their behavior, such as filtering out unowned keys from read-only requests during ASM operations.

‎content/commands/info.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,9 @@ Here is the meaning of all fields in the **memory** section:
199199
* `mem_clients_slaves`: Memory used by replica clients - Starting Redis 7.0, replica buffers share memory with the replication backlog, so this field can show 0 when replicas don't trigger an increase of memory usage.
200200
* `mem_clients_normal`: Memory used by normal clients
201201
* `mem_cluster_links`: Memory used by links to peers on the cluster bus when cluster mode is enabled.
202+
* `mem_cluster_slot_migration_output_buffer`: Memory usage of the migration client's output buffer. Redis writes incoming changes to this buffer during the migration process.
203+
* `mem_cluster_slot_migration_input_buffer`: Memory usage of the accumulated replication stream buffer on the importing node.
204+
* `mem_cluster_slot_migration_input_buffer_peak`: Peak accumulated repl buffer size on the importing side.
202205
* `mem_aof_buffer`: Transient memory used for AOF and AOF rewrite buffers
203206
* `mem_replication_backlog`: Memory used by replication backlog
204207
* `mem_total_replication_buffers`: Total memory consumed for replication buffers - Added in Redis 7.0.
@@ -501,9 +504,16 @@ The **sentinel** section is only available in Redis Sentinel instances. It consi
501504
* `sentinel_scripts_queue_length`: The length of the queue of user scripts that are pending execution
502505
* `sentinel_simulate_failure_flags`: Flags for the `SENTINEL SIMULATE-FAILURE` command
503506

504-
The **cluster** section currently only contains a unique field:
507+
The **cluster** section contains the following fields:
505508

506509
* `cluster_enabled`: Indicate Redis cluster is enabled
510+
* `cluster_slot_migration_active_tasks`: Number of in-progress ASM tasks. Currently, it will be 1 or 0.
511+
* `cluster_slot_migration_active_trim_running`: Number of active trim jobs in progress and scheduled.
512+
* `cluster_slot_migration_active_trim_current_job_keys`: Number of keys scheduled for deletion in the current trim job.
513+
* `cluster_slot_migration_active_trim_current_job_trimmed`: Number of keys already deleted in the current trim job.
514+
* `cluster_slot_migration_stats_active_trim_started`: Total number of trim jobs that have started since the process began.
515+
* `cluster_slot_migration_stats_active_trim_completed`: Total number of trim jobs completed since the process began.
516+
* `cluster_slot_migration_stats_active_trim_cancelled`: Total number of trim jobs cancelled since the process began.
507517

508518
The **modules** section contains additional information about loaded modules if the modules provide it. The field part of property lines in this section are always prefixed with the module's name.
509519

0 commit comments

Comments
 (0)