From 06cba6ccd165ca8b224797e37fccb9e63f026d77 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 21 Mar 2020 11:28:17 +0100 Subject: Adding upstream version 1.9.1. Signed-off-by: Daniel Baumann --- iredis/data/commands/cluster-forget.md | 59 ++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 iredis/data/commands/cluster-forget.md (limited to 'iredis/data/commands/cluster-forget.md') diff --git a/iredis/data/commands/cluster-forget.md b/iredis/data/commands/cluster-forget.md new file mode 100644 index 0000000..7926091 --- /dev/null +++ b/iredis/data/commands/cluster-forget.md @@ -0,0 +1,59 @@ +The command is used in order to remove a node, specified via its node ID, from +the set of _known nodes_ of the Redis Cluster node receiving the command. In +other words the specified node is removed from the _nodes table_ of the node +receiving the command. + +Because when a given node is part of the cluster, all the other nodes +participating in the cluster knows about it, in order for a node to be +completely removed from a cluster, the `CLUSTER FORGET` command must be sent to +all the remaining nodes, regardless of the fact they are masters or replicas. + +However the command cannot simply drop the node from the internal node table of +the node receiving the command, it also implements a ban-list, not allowing the +same node to be added again as a side effect of processing the _gossip section_ +of the heartbeat packets received from other nodes. + +## Details on why the ban-list is needed + +In the following example we'll show why the command must not just remove a given +node from the nodes table, but also prevent it for being re-inserted again for +some time. + +Let's assume we have four nodes, A, B, C and D. In order to end with just a +three nodes cluster A, B, C we may follow these steps: + +1. Reshard all the hash slots from D to nodes A, B, C. +2. D is now empty, but still listed in the nodes table of A, B and C. +3. We contact A, and send `CLUSTER FORGET D`. +4. B sends node A a heartbeat packet, where node D is listed. +5. A does no longer known node D (see step 3), so it starts an handshake with D. +6. D ends re-added in the nodes table of A. + +As you can see in this way removing a node is fragile, we need to send +`CLUSTER FORGET` commands to all the nodes ASAP hoping there are no gossip +sections processing in the meantime. Because of this problem the command +implements a ban-list with an expire time for each entry. + +So what the command really does is: + +1. The specified node gets removed from the nodes table. +2. The node ID of the removed node gets added to the ban-list, for 1 minute. +3. The node will skip all the node IDs listed in the ban-list when processing + gossip sections received in heartbeat packets from other nodes. + +This way we have a 60 second window to inform all the nodes in the cluster that +we want to remove a node. + +## Special conditions not allowing the command execution + +The command does not succeed and returns an error in the following cases: + +1. The specified node ID is not found in the nodes table. +2. The node receiving the command is a replica, and the specified node ID + identifies its current master. +3. The node ID identifies the same node we are sending the command to. + +@return + +@simple-string-reply: `OK` if the command was executed successfully, otherwise +an error is returned. -- cgit v1.2.3