gRPC services

Detailed look at each gRPC service. Source: api/etcdserverpb/rpc.proto. Implementation: server/etcdserver/api/v3rpc/.

KV

service KV {
    rpc Range(RangeRequest) returns (RangeResponse);
    rpc RangeStream(RangeRequest) returns (stream RangeStreamResponse);
    rpc Put(PutRequest) returns (PutResponse);
    rpc DeleteRange(DeleteRangeRequest) returns (DeleteRangeResponse);
    rpc Txn(TxnRequest) returns (TxnResponse);
    rpc Compact(CompactionRequest) returns (CompactionResponse);
}

Notable fields:

• RangeRequest.serializable — skip Raft ReadIndex; may return stale data.
• RangeRequest.linearizable (default) — go through Raft for linearizable reads.
• RangeRequest.keys_only, count_only, min_mod_revision, max_mod_revision, sort_target, sort_order — extensive filtering knobs.
• RangeStream is gRPC-only (no REST mapping in rpc.proto); it lets the server chunk huge result sets.
• Compact.physical=true blocks the response until the bbolt-level reclaim has run.

Implementation: server/etcdserver/api/v3rpc/key.go, quota.go.

Watch

service Watch {
    rpc Watch(stream WatchRequest) returns (stream WatchResponse);
}

Bidirectional stream — see features/watch. The server sends created, canceled, compact_revision, progress_notify, and fragment flags on responses to coordinate with clients.

Implementation: server/etcdserver/api/v3rpc/watch.go.

Lease

service Lease {
    rpc LeaseGrant(LeaseGrantRequest) returns (LeaseGrantResponse);
    rpc LeaseRevoke(LeaseRevokeRequest) returns (LeaseRevokeResponse);
    rpc LeaseKeepAlive(stream LeaseKeepAliveRequest) returns (stream LeaseKeepAliveResponse);
    rpc LeaseTimeToLive(LeaseTimeToLiveRequest) returns (LeaseTimeToLiveResponse);
    rpc LeaseLeases(LeaseLeasesRequest) returns (LeaseLeasesResponse);
}

LeaseKeepAlive is a bidi stream — clients send periodic renewals and receive the granted TTL. Implementation: server/etcdserver/api/v3rpc/lease.go.

Cluster

service Cluster {
    rpc MemberAdd(MemberAddRequest) returns (MemberAddResponse);
    rpc MemberRemove(MemberRemoveRequest) returns (MemberRemoveResponse);
    rpc MemberUpdate(MemberUpdateRequest) returns (MemberUpdateResponse);
    rpc MemberList(MemberListRequest) returns (MemberListResponse);
    rpc MemberPromote(MemberPromoteRequest) returns (MemberPromoteResponse);
}

Each mutation is a Raft ConfChange. See features/learner-promotion.

Implementation: server/etcdserver/api/v3rpc/member.go.

Maintenance

service Maintenance {
    rpc Alarm(AlarmRequest) returns (AlarmResponse);
    rpc Status(StatusRequest) returns (StatusResponse);
    rpc Defragment(DefragmentRequest) returns (DefragmentResponse);
    rpc Hash(HashRequest) returns (HashResponse);
    rpc HashKV(HashKVRequest) returns (HashKVResponse);
    rpc Snapshot(SnapshotRequest) returns (stream SnapshotResponse);
    rpc MoveLeader(MoveLeaderRequest) returns (MoveLeaderResponse);
    rpc Downgrade(DowngradeRequest) returns (DowngradeResponse);
}

Operator/admin surface. Snapshot is a streaming download of the live bbolt DB. Implementation: server/etcdserver/api/v3rpc/maintenance.go.

Auth

service Auth {
    rpc AuthEnable / AuthDisable / Authenticate
    rpc UserAdd / UserGet / UserList / UserDelete / UserChangePassword / UserGrantRole / UserRevokeRole
    rpc RoleAdd / RoleGet / RoleList / RoleDelete / RoleGrantPermission / RoleRevokePermission
}

All mutations go through Raft. Authentication tokens are returned in the response; clients send them back in the gRPC token metadata header.

Implementation: server/etcdserver/api/v3rpc/auth.go.

Lock and Election (v3lock / v3election)

These are convenience services that wrap distributed primitives in gRPC form so non-Go clients can use them. See features/distributed-primitives.

Health

grpc.health.v1.Health is registered by server/etcdserver/api/v3rpc/health.go. It returns SERVING when the member can serve requests; load balancers and Kubernetes probes use it as the primary readiness signal.

Authorization headers

Every response includes a ResponseHeader carrying cluster_id, member_id, revision, raft_term. Clients use revision to chain reads/watches and to detect stale data.