Redpanda’s seed server bootstrap is the magical incantation that brings your initial cluster to life, but it’s also where many new clusters go to die.
Let’s see Redpanda in action, bootstrapping a single-node cluster.
rpk cluster bootstrap --seed-addr 127.0.0.1:33145 --node-id 0 --listen-addr 127.0.0.1:9092 --advertise-addr 127.0.0.1:9092
This command tells Redpanda:
--seed-addr 127.0.0.1:33145: This node will advertise itself as a seed server on this specific IP and port. Other nodes will use this to find it.--node-id 0: Assigns a unique ID to this Redpanda instance. Crucial for cluster membership.--listen-addr 127.0.0.1:9092: The IP and port Redpanda will listen on for client connections (Kafka clients, etc.).--advertise-addr 127.0.0.1:9092: The IP and port Redpanda will advertise to other brokers and clients. This is what other nodes will try to connect to.
The core problem Redpanda solves here is distributed consensus in a fault-tolerant way, specifically for Kafka-like messaging. It needs to establish a quorum of nodes that agree on the state of the cluster, the topics, and the data. The bootstrap process is the very first step in forming that agreement.
Internally, Redpanda uses the Raft consensus algorithm. The bootstrap command initiates a Raft group for cluster metadata (like _redpanda.cluster_api). The first node to start bootstraps itself by creating this initial Raft group, becoming the sole member and leader. Subsequent nodes joining the cluster will attempt to connect to a seed server, discover the existing cluster configuration, and then join the Raft group, eventually working towards a stable quorum.
The rpk cluster bootstrap command is your primary tool. The essential flags are --seed-addr and --node-id. The --seed-addr is the IP:port combination that other nodes will use to discover the initial node(s) in the cluster. On the first node, this is typically an IP address and a port that Redpanda will bind to for discovery. The --node-id must be unique for each Redpanda instance in the cluster.
When bootstrapping a multi-node cluster, you’d run rpk cluster bootstrap on the first node. Then, for each subsequent node, you would run rpk cluster join and point it to the --seed-addr of the already bootstrapped node.
For example, to join a second node:
rpk cluster join --seed-addr <ip_of_first_node>:33145 --node-id 1 --listen-addr 127.0.0.1:9093 --advertise-addr 127.0.0.1:9093
Here, --seed-addr <ip_of_first_node>:33145 is the critical piece. The new node uses this to find the existing cluster. --node-id 1 ensures it has a unique identity.
The --listen-addr and --advertise-addr for client connections (9092 by default for Kafka) can be the same or different, depending on your network setup. The --advertise-addr is what other brokers and clients will see and attempt to connect to. If your nodes are running in Docker or on different machines, the advertise-addr should be reachable from other nodes.
The --seed-addr is specifically for the inter-broker communication and discovery mechanism, often on a different port than the client-facing one. For a single node, 127.0.0.1:33145 is common. For multi-node, it’s the IP/port of one of the existing brokers that the new node can reach.
The rpk tool is essentially a client to the Redpanda control plane. When you run bootstrap, rpk talks to the Redpanda agent on that node to configure its initial state. For join, rpk tells the new Redpanda agent which existing nodes (seeds) to contact to learn about the cluster.
What most people miss is that the --seed-addr value itself must be resolvable and reachable by the joining node. If you’re bootstrapping on 10.0.0.1 and trying to join from 10.0.0.2, you can’t use 127.0.0.1:33145 for the seed address. You need to use the actual IP address of the first node that the second node can route to.
The next step after a successful bootstrap and join is usually configuring topic creation and understanding partition leader election.