CLUSTER-MEET(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 CLUSTER-MEET 💖

okay bestie, welcome to the Valkey Command Manual, page CLUSTER-MEET(3valkey) — this is the one where you literally introduce your server nodes to each other. it's giving ✨networking mixer✨.

🌸 NAME 🌸

cluster-meet — forces a node to handshake with another node. that's it. that's the whole job. iconic behavior honestly.

🎀 SYNOPSIS 🎀

CLUSTER MEET ip port [cluster-bus-port]

🦋 DESCRIPTION 🦋

so here's the tea. CLUSTER MEET is what you use to connect different Valkey nodes that have cluster support enabled into one working cluster. it's the glue, it's the group chat invite, it's the whole vibe.

the basic idea — and this is lowkey the important part — is that nodes by default don't trust each other. they're considered unknown. and that's on purpose, because otherwise you'd get different clusters accidentally merging into one giant mess due to system administration errors or network address modifications. nobody wants that. 💀

so for a given node to accept another one into the list of nodes composing a Valkey Cluster, there are literally only two ways:

  1. The system administrator sends a CLUSTER MEET command to force a node to meet another one.
  2. An already known node sends a list of nodes in the gossip section that we are not aware of. If the receiving node trusts the sending node as a known node, it will process the gossip section and send a handshake to the nodes that are still not known.

now — important nuance, don't skip this — Valkey Cluster needs to form a full mesh (each node is connected with each other node). but to create a cluster, there is no need to send all the CLUSTER MEET commands needed to form the full mesh. what matters is to send enough CLUSTER MEET messages so that each node can reach each other node through a chain of known nodes. thanks to the exchange of gossip information in heartbeat packets, the missing links will be created. the cluster fills itself in. self-care. 💅

so, if we link node A with node B via CLUSTER MEET, and B with C, A and C will find their ways to handshake and create a link. they figure it out. main character energy fr fr.

another example: imagine a cluster formed of the following four nodes called A, B, C and D. we may send just the following set of commands to A:

  1. CLUSTER MEET B-ip B-port
  2. CLUSTER MEET C-ip C-port
  3. CLUSTER MEET D-ip D-port

as a side effect of A knowing and being known by all the other nodes, it will send gossip sections in the heartbeat packets that will allow each other node to create a link with each other one, forming a full mesh in a matter of seconds, even if the cluster is large. obsessed. 🔥

moreover CLUSTER MEET does not need to be reciprocal. if I send the command to A in order to join B, I don't need to also send it to B in order to join A. no mutuals required bestie, it's not that kind of app.

if the optional cluster_bus_port argument is not provided, the default of port + 10000 will be used.

🧚 Implementation details: MEET and PING packets 🧚

when a given node receives a CLUSTER MEET message, the node specified in the command still does not know the node we sent the command to. so in order for the node to force the receiver to accept it as a trusted node, it sends a MEET packet instead of a PING packet. the two packets have exactly the same format, but the former forces the receiver to acknowledge the node as trusted. same fit, different attitude. ✨

💜 REPLY 💜

valkey-protocol(7) Simple string reply: OK if the command was successful. if the port or cluster bus port number is out of range, or if an invalid address is specified, an error is returned.

so like… if you hand it a bad port or a nonsense address, it's not gonna be nice about it. it errors. correct.

🌈 COMPLEXITY 🌈

O(1)

constant time, no notes, ate and left no crumbs.

👑 ACL CATEGORIES 👑

@admin @dangerous @slow

yes bestie it's flagged dangerous. it's literally introducing strangers to your cluster. respect the flag. 🙈

⭐ HISTORY ⭐

  • Available since: 3.0.0
  • Changed in 4.0.0: Added the optional cluster_bus_port argument.

🫶 SEE ALSO 🫶

and that's the whole page bestie 💖 this one shipped in Valkey 9.0.0, dated 2025-10-21, and it lives under CLUSTER-MEET(3valkey) — go forth and introduce your nodes to each other, they'll do the rest 🦋✨

📦 where this page comes from