Proto files

Where each .proto lives, what it owns, and what generated artifacts come out of it.

Locations

File	Purpose
api/etcdserverpb/rpc.proto	Public RPC surface — KV, Watch, Lease, Auth, Cluster, Maintenance, plus all request/response messages
api/etcdserverpb/etcdserver.proto	Vestigial v2 request type used internally
api/etcdserverpb/raft_internal.proto	Internal InternalRaftRequest envelope written into Raft log
api/mvccpb/kv.proto	KeyValue, Event
api/authpb/auth.proto	User, Role, Permission
api/membershippb/membership.proto	Member, ClusterVersionSet, Downgrade
api/versionpb/version.proto	Cluster version negotiation messages
server/etcdserver/api/v3lock/v3lockpb/v3lock.proto	Lock/Unlock service
server/etcdserver/api/v3election/v3electionpb/v3election.proto	Campaign/Proclaim/Resign/Leader/Observe
server/lease/leasepb/lease.proto	On-disk encoding of a lease
server/storage/wal/walpb/record.proto	WAL record envelope
server/etcdserver/api/snap/snappb/snap.proto	Snapshot file header

Generation

scripts/genproto.sh regenerates everything — *.pb.go, *_grpc.pb.go, *.pb.gw.go, and (when wired) the swagger document. The tooling versions are pinned in tools/mod/go.mod:

• protoc 3.20.3 (downloaded by the script if absent)
• protoc-gen-go, protoc-gen-go-grpc
• protoc-gen-grpc-gateway, protoc-gen-openapiv2

Verification: scripts/verify_genproto.sh regenerates into a temp dir and diffs against the committed output. CI runs this on every PR.

Annotations

scripts/etcd_version_annotations.txt is a curated matrix of which release first introduced each RPC. scripts/verify_proto_annotations.sh enforces that new methods include their version annotation; scripts/update_proto_annotations.sh regenerates the file. The Go program backing both lives at tools/proto-annotations/.

This system is etcd's defense against accidental wire-protocol regressions — if you remove or rename an existing field, the verifier flags it.

Editing tips

• Never reorder fields; only append.
• Use optional only after a careful look at older clients' behavior.
• Mutations to rpc.proto typically need updates in:
  1. server/etcdserver/api/v3rpc/<service>.go — the server handler.
  2. server/etcdserver/v3_server.go — the EtcdServer method.
  3. server/etcdserver/apply/<area>.go — apply-time logic.
  4. client/v3/<area>.go — the Go client.
  5. etcdctl/ctlv3/command/<verb>_command.go — operator surface.
  6. Tests across tests/integration/ and tests/e2e/.