Gossip

pkg/gossip/ is a small, eventually-consistent overlay network used to spread cluster-wide ephemeral state. Each node connects to a few peers and exchanges typed key/value pairs; values reach every node in O(log N) rounds.

Purpose

Some cluster-wide state is too small to require Raft and too high-frequency to query repeatedly through KV. Gossip is the answer: node addresses, store descriptors, the cluster ID, the system config (legacy zone-config blob), the deprecated descriptor cache, and a handful of bootstrap-time signals.

What's gossiped today

A non-exhaustive list (search for gossip.AddInfo and the KeyXxx constants in pkg/gossip/keys.go):

• Cluster ID and node ID assignment.
• Node descriptors — addresses, locality, build info; gossiped under node:<nodeID>.
• Store descriptors — capacity, used, queries-per-second, replica counts; updated periodically by each store.
• Liveness gossip key — used as a fast hint; the source of truth is the liveness range.
• First range descriptor — so any node can locate the meta range without already knowing it.
• System config (legacy) — used to be the path for zone configs before spanconfig. Still in use during upgrades.
• DistSQL flow registration — gateway nodes' addresses for in-flight flows.

Directory layout

pkg/gossip/
├── BUILD.bazel
├── gossip.go            // top-level Gossip type
├── infostore.go         // local infostore: typed in-memory KV
├── client.go            // outbound connection to a peer
├── server.go            // inbound connection handler
├── keys.go              // canonical gossip keys (constants)
└── …

Key types

Type	File	Description
Gossip	pkg/gossip/gossip.go	The top-level type; one per node.
infoStore	pkg/gossip/infostore.go	Local typed map of gossip values plus version counters.
client / server	pkg/gossip/client.go, pkg/gossip/server.go	Long-running connections to peer nodes.
Callback	pkg/gossip/gossip.go	Subscriber callback for a key prefix.

How a value spreads

sequenceDiagram
  participant A as Node A
  participant B as Node B (gossip peer)
  participant C as Node C
  A->>A: AddInfo("store:1", desc)
  A->>B: gossip.Push (infos with version > B's view)
  B->>B: merge into infoStore, fire callbacks
  B->>C: forward newer infos on next tick
  C->>C: merge, fire callbacks

Each node tracks per-key versions; only newer versions propagate. Callbacks registered via gossip.RegisterCallback("store:.*", fn) fire when any matching key changes.

Topology

Gossip uses a small fan-out (typically 3 outgoing peers per node) and prefers peers in different localities to keep redundancy. Bootstrap addresses (--join) seed the connection graph; over time, nodes discover and prefer better peers via the gossip-of-gossip-state protocol.

Why ranges aren't gossiped

Range metadata used to be gossiped in early CockroachDB versions but was moved to the meta-range KV path because it scaled poorly past a few thousand ranges. Today only the first range descriptor is gossiped — enough to bootstrap meta lookups.

Entry points for modification

• New gossiped key: add a constant in pkg/gossip/keys.go, document its TTL, and have the producer call gossip.AddInfo. Subscribers register a callback.
• Tweak fan-out / TTLs: cluster settings under gossip.* are wired into infoStore.

Related pages

• KV server — the largest producer of store descriptors.
• Server — pkg/server/node.go initializes the local gossip instance.
• RPC — gossip dials peers via nodedialer.
• Span config — replaces the legacy gossiped system config.