Learner promotion

The recommended way to add a member to an etcd cluster is in learner state. Learners participate in log replication but do not vote, so they cannot delay quorum during catch-up.

Lifecycle

stateDiagram-v2
    [*] --> Joining: etcdctl member add --learner
    Joining --> CatchingUp: ConfChange committed
    CatchingUp --> Ready: progress >= 90%
    Ready --> Voter: etcdctl member promote
    Voter --> [*]

Once promoted, a learner becomes a regular voting member; quorum size potentially grows by one.

Server-side gating

EtcdServer.PromoteMember (server/etcdserver/server.go) enforces:

• The member exists and is currently a learner.
• The leader's view of the learner's Match index is at least readyPercentThreshold (= 0.9) * leader.Match.
• The cluster is otherwise healthy (no in-flight conf change, no NOSPACE/CORRUPT alarm).

If any guard fails the operator gets ErrLearnerNotReady and the request is rejected without proposing a ConfChange.

Where the bits live

Concern	Location
Learner flag in protobuf	api/membershippb/membership.proto (MemberAttributes.IsLearner)
Per-member tracking	server/etcdserver/api/membership/member.go::RaftAttributes.IsLearner
Conf-change application	server/etcdserver/api/membership/cluster.go::ApplyConfChange
Promotion API	server/etcdserver/api/v3rpc/member.go::MemberPromote -> EtcdServer.PromoteMember
Operator command	etcdctl member promote <member-id> (etcdctl/ctlv3/command/member_command.go)
Tests	tests/integration/v3_grpc_test.go, tests/e2e/, plus robustness scenarios

Operational notes

• A cluster cannot have more than one learner at a time (server-side guard).
• During the catch-up phase, etcdctl endpoint status shows the learner with Learner: true and a smaller Match than the leader.
• Promotion is itself a ConfChange; it goes through Raft and is therefore atomic.

Cross-references

• features/clustering-discovery — how a learner first joins.
• systems/membership — the data structures.
• systems/raft — ConfChange semantics.