Clustering and discovery

How an etcd member finds its peers at boot and how the cluster state evolves over time.

Bootstrap modes

Mode	Trigger	Source
Static	--initial-cluster= / --initial-cluster-state=new	server/embed/config.go
DNS SRV	--discovery-srv=example.com	client/pkg/v3/srv/srv.go
Discovery v3	--discovery-endpoints= and --discovery-token=	server/etcdserver/api/v3discovery/
Existing	--initial-cluster-state=existing	Member rejoins a known cluster

In static mode each member is told the full topology up front. DNS SRV lets DNS act as the source of truth — useful in container orchestrators. Discovery v3 delegates roster bootstrap to a public or private etcd cluster acting as the discovery server (this replaced the legacy https://discovery.etcd.io/ HTTP service).

Joining flow

sequenceDiagram
    participant New as new member
    participant Leader as cluster leader
    participant Cluster as RaftCluster

    New->>Leader: MemberAdd(peerURLs, IsLearner=true)
    Leader->>Cluster: propose ConfChange
    Cluster->>New: ConfChange committed
    New->>Leader: rafthttp join
    Leader->>New: snapshot install (if needed)
    New->>Cluster: catch up via WAL replay
    Operator->>Leader: MemberPromote(memberID)
    Leader->>Cluster: propose ConfChange (Promote)
    Cluster->>New: now a voting member

Adding members as learners first is the recommended path (--enable-v2-discovery=true is no longer relevant in v3.x). The promotion check in server/etcdserver/server.go::PromoteMember requires readyPercentThreshold = 0.9.

Health checks during reconfiguration

--strict-reconfig-check (default true) gates conf changes that would lose quorum. RaftCluster.ValidateConfigurationChange in server/etcdserver/api/membership/cluster.go runs the gating logic.

Members and their attributes

A Member (server/etcdserver/api/membership/member.go) carries:

• ID — 64-bit derived from name + cluster ID.
• RaftAttributes: PeerURLs, IsLearner.
• Attributes: Name, ClientURLs.

Peer attributes change via ConfChange; client attributes change via a normal Raft entry through applyV3.UpdateAttributes.

Discovery v3 internals

server/etcdserver/api/v3discovery/discovery.go:

1. Connects to a discovery cluster as a regular clientv3.Client.
2. Registers itself under /_etcd/registry/<token>/<member>.
3. Watches the prefix until the size matches --initial-cluster-token's expected member count.
4. Returns the resulting roster to embed.StartEtcd.

It replaces the older server/etcdserver/api/v2discovery/, which was a thin HTTP client.

Cross-references

• systems/membership — the data model.
• features/learner-promotion — the promotion lifecycle in detail.
• systems/raft — ConfChange handling.