A Valkey cluster doesn’t actually shard data across nodes in the way you might intuitively think. Instead, it assigns hash slots to nodes, and your data is automatically routed to the correct node based on the hash of its key.
Let’s see this in action. Imagine a simple cluster with two master nodes, node1 and node2.
First, we need to set up the cluster. This typically involves starting your Valkey instances with the --cluster-enabled yes and --cluster-config-file options, and then using the redis-cli --cluster create command.
# On node1 (e.g., IP 192.168.1.10, port 7000)
valkey-server /path/to/valkey.conf --cluster-enabled yes --cluster-config-file nodes-7000.conf
# On node2 (e.g., IP 192.168.1.11, port 7000)
valkey-server /path/to/valkey.conf --cluster-enabled yes --cluster-config-file nodes-7000.conf
# From any machine that can reach both nodes:
redis-cli --cluster create 192.168.1.10:7000 192.168.1.11:7000 --cluster-replicas 1
The create command will prompt you to confirm the setup. It will automatically divide the 16384 hash slots between the nodes. For two nodes, it might look something like this:
>>> Performing hash slots allocation on 2 nodes...
Master[0] -> Slots 0 - 8191
Master[1] -> Slots 8192 - 16383
Now, when you interact with the cluster using redis-cli --cluster <command>, it knows where to send your data.
Let’s add a key-value pair.
# Connect to any node in the cluster
redis-cli -c -p 7000
# Set a key
127.0.0.1:7000> SET mykey "myvalue"
-> Redirected to slot [6789] via CLUSTER KEYSLOT mykey: 127.0.0.1:7000
OK
127.0.0.1:7000> GET mykey
-> Redirected to slot [6789] via CLUSTER KEYSLOT mykey: 127.0.0.1:7000
"myvalue"
Notice the -> Redirected to slot ... messages. This is the cluster’s redirection mechanism at play. redis-cli -c is in cluster mode, so it automatically handles these redirects. The client asks the cluster which node is responsible for the hash slot of mykey. The cluster responds with the node’s address, and redis-cli transparently sends the command there.
The core concept is hash slots. Valkey divides the entire key space into 16384 hash slots. Each master node in the cluster is responsible for a contiguous range of these slots. When you set or get a key, Valkey calculates HASH_SLOT = HASH(key) % 16384. This slot number is then mapped to the master node that owns it.
The CLUSTER KEYSLOT <key> command reveals this mapping:
127.0.0.1:7000> CLUSTER KEYSLOT mykey
(integer) 6789
If you then check which node owns slot 6789:
127.0.0.1:7000> CLUSTER NODES
...
<node_id_of_node1> 192.168.1.10:7000@XXXX master - 0 1678886400000 1 connected 0-8191
<node_id_of_node2> 192.168.1.11:7000@XXXX master - 0 1678886401000 2 connected 8192-16383
...
This output shows that node1 (192.168.1.10:7000) is responsible for slots 0 through 8191, and node2 for 8192 through 16383. Since 6789 falls within 0-8191, mykey resides on node1.
This sharding by hash slots is how Valkey achieves horizontal scaling. You can add more master nodes, and the cluster will rebalance the hash slots across them. The redis-cli --cluster rebalance command initiates this process.
The key mechanism enabling this distribution is the CLUSTER KEYSLOT calculation and the CLUSTER NODES information that each node maintains. Clients query this information to route commands. If a client sends a command for a key to the wrong node, that node will respond with a MOVED error, instructing the client to resend the command to the correct node. The -c flag in redis-cli handles these MOVED redirects automatically.
A common pitfall is using keys that don’t hash consistently or keys that span multiple slots. Valkey supports hash tags, where a part of the key enclosed in curly braces {...} is used for hashing. For example, user:{123}:profile and user:{123}:settings will both hash to the same slot because only 123 is considered for the hash. This is crucial for operations that require multiple keys to reside on the same node, like transactions (MULTI/EXEC) or Lua scripts.
The next concept you’ll grapple with is handling node failures and promoting replicas to masters.