PATTERN Cited by 1 source

Seed-node bootstrap¶

The seed-node bootstrap pattern addresses one specific problem in gossip-based clusters: "How does a freshly-booting node find anyone?"

Gossip protocols rely on each node already having a partial view of the cluster to pick its next gossip peer — but a node with no partial view (first boot, crash-recovery, or wire-reset) has nothing to gossip to. Seed nodes are the answer: a statically-configured list of fully-functional peers that every node is guaranteed to know.

Mechanism¶

Every node's configuration file contains a seed_nodes = [...] list.
On boot, the node contacts a seed node and initiates a gossip exchange to pull the current partial view.
The node integrates the returned member list into its own peer-sampling service and begins normal gossip.
Seed nodes are regular cluster members — the only thing special about them is that their addresses appear in everybody's static config.

Why it's needed — "prevent logical divisions"¶

From sources/2023-07-16-highscalability-gossip-protocol-explained:

"Every node in the system must be aware of the seed nodes. The gossip system interacts with the seed nodes to prevent logical divisions."

Without seeds, two sub-clusters that booted in isolation will both gossip happily within themselves — but never between each other. That's a permanent split-brain that looks healthy from inside each half. Seed nodes, by being known to both halves, guarantee the gossip graph is connected at boot time.

Design checklist¶

≥ 2 seeds per cluster, ideally spread across failure domains (racks, AZs). A single seed is a single point of bootstrap failure.
Seeds are identical to non-seeds at runtime — a seed is just a node whose address happens to be listed. Don't make seed-vs-non-seed a runtime protocol distinction.
Document seeds in immutable configuration — they belong in infra-as-code, not in a hand-edited runtime config.
Rotation discipline — when a seed is decommissioned, update every node's seed list before removing it. An orphaned seed config leaves new nodes unable to bootstrap.
DNS as indirection — publishing seeds behind a DNS name (e.g. seed.cluster.internal resolving to multiple IPs) lets you rotate IPs without touching node config.

Canonical implementations¶

Apache Cassandra — seed_provider directive, seeds list; Cassandra's docs explicitly warn "treat seeds specially — don't bootstrap new nodes from seed nodes".
Consul — retry_join (renamed from start_join) list; -bootstrap-expect on the server side converges on the initial cluster size.
Riak — cluster-join via seed-node command.
Fly.io Corrosion — bootstrap via the fully-connected WireGuard mesh; the mesh removes the "how do I find anyone?" sub-problem, so seeds are effectively implicit.

Seen in¶

sources/2023-07-16-highscalability-gossip-protocol-explained — definitional source.