Membership

Source: server/etcdserver/api/membership/.

Purpose

The membership package owns the cluster roster — who are the members, what are their peer URLs, what is their version, what is the cluster ID. It is consulted on every RPC, mutated by Raft ConfChange entries, and persisted in both the v2 store (legacy compatibility) and the v3 bbolt schema.

Directory layout

server/etcdserver/api/membership/
├── cluster.go         # RaftCluster: roster, conf-change application, voting/learner predicates
├── member.go          # Member struct, ID generation
├── store.go, storev2.go # Persistence (v2 + v3 backends)
├── errors.go
├── metrics.go
└── *_test.go

Key abstractions

Symbol	File	Description
RaftCluster	server/etcdserver/api/membership/cluster.go	Mutable roster; methods like AddMember, RemoveMember, PromoteMember, UpdateAttributes
Member	server/etcdserver/api/membership/member.go	ID, Name, RaftAttributes (peer URLs, IsLearner), Attributes (client URLs)
RaftAttributes / Attributes	same	The two halves of the member model — peer-side and client-side
ClusterID	derived	64-bit hash of initial cluster definition

How it works

• On bootstrap, embed.Etcd constructs a RaftCluster from --initial-cluster (or discovery output), which is fed to the Raft library as the initial conf state.
• Every later change is a Raft ConfChange entry (or an attribute-update normal entry). When apply sees one, it calls into RaftCluster.ApplyConfChange (server/etcdserver/apply/).
• Learners (Member.IsLearner = true) participate in log replication but do not count toward quorum until promoted.
• Promotion is gated by a "ready percent" check: a learner must have caught up to within readyPercentThreshold = 0.9 of the leader's progress (server/etcdserver/server.go).

Persistence

Two parallel paths exist for legacy reasons:

• v2 store (storev2.go) — JSON-encoded members under /0/members/<id>. Still used by some tooling.
• v3 bbolt schema (store.go plus server/storage/schema/membership.go) — the modern path.

Both are written on every change; the v2 path is gradually being phased out.

Integration points

• Raft drives ConfChange entries; server/etcdserver/raft.go handles the applyConfChange callback.
• Peer transport (rafthttp) is reconfigured whenever a member is added/removed.
• API surfaces:
  • gRPC: server/etcdserver/api/v3rpc/member.go (MemberAdd, MemberRemove, MemberPromote, MemberList).
  • HTTP: server/etcdserver/api/etcdhttp/peer.go exposes /members for peer health.
• Discovery (server/etcdserver/api/v3discovery/) consults this package to advertise endpoints.

Entry points for modification

• New member field → Member + RaftAttributes/Attributes, api/membershippb/membership.proto (regen), server/storage/schema/membership.go.
• New conf-change handling → cluster.go::ApplyConfChange and server/etcdserver/apply/.
• New gRPC method → member.go in v3rpc/.

Cross-references

• Apply pipeline for how conf changes commit.
• Features → learner promotion for the promotion lifecycle.