etcd

The cluster member binary. Source: server/.

Purpose

etcd is the long-running daemon that participates in the Raft cluster, persists state to disk, and serves clients over gRPC. The same binary additionally implements two stateless modes — gateway and grpc-proxy — selected by a positional subcommand.

Directory layout

server/
├── main.go                 # entry point (calls etcdmain.Main)
├── etcdmain/               # flag parsing & mode dispatch (etcd.go, gateway.go, grpc_proxy.go, help.go)
├── embed/                  # public Go API (embed.Etcd, embed.Config)
├── etcdserver/             # core server: server.go, raft.go, v3_server.go, apply/, txn/, ...
│   └── api/                # gRPC + HTTP surfaces (v3rpc, etcdhttp, rafthttp, snap, ...)
├── auth/                   # RBAC, JWT/simple tokens
├── lease/                  # TTL leases
├── storage/                # MVCC, backend (bbolt), WAL, schema
├── proxy/                  # grpcproxy + tcpproxy implementations
├── features/               # feature-gate definitions
├── config/                 # server-side config helpers
├── verify/                 # invariants asserted at startup / shutdown
└── mock/                   # test doubles

Key abstractions

Symbol	File	Description
etcdmain.Main(args)	server/etcdmain/main.go, server/etcdmain/etcd.go	Top-level dispatch; chooses server/gateway/grpc-proxy.
embed.Etcd	server/embed/etcd.go	The library form — fully-running etcd accessible from another Go program.
embed.Config	server/embed/config.go	All flag-driven configuration (1,403-line file; the source of truth for every option).
etcdserver.EtcdServer	server/etcdserver/server.go	The actual server struct; owns Raft node, MVCC, leases, auth, peer transport.
etcdserver.raftNode	server/etcdserver/raft.go	Drives the Raft Ready loop, persists entries, propagates messages.
etcdserver/apply.uberApplier	server/etcdserver/apply/uber_applier.go	Applies committed entries against MVCC/lease/auth.
v3rpc.kvServer, watchServer, leaseServer, authServer, clusterServer, maintenanceServer	server/etcdserver/api/v3rpc/	Implements the gRPC services.
rafthttp.Transport	server/etcdserver/api/rafthttp/transport.go	HTTP-based peer transport with stream + pipeline channels.

How it works

1. etcdmain.Main parses flags into embed.Config (server/etcdmain/config.go).
2. If running as a member: embed.StartEtcd(cfg) constructs an embed.Etcd, which:
   • Sets up TLS listeners for client (:2379) and peer (:2380) URLs.
   • Constructs the storage stack (backend, mvcc, wal, schema).
   • Creates the Raft node and EtcdServer.
   • Starts the gRPC server, the HTTP health/metrics server, and (optionally) the v2 store / discovery client.
3. EtcdServer.run() drives the Ready loop:
   • Reads Ready from raft, persists entries via WAL, sends messages via rafthttp, and forwards committed entries to the apply pipeline.
4. Clients hit gRPC handlers in server/etcdserver/api/v3rpc/, which delegate to EtcdServer.Range/Put/Txn/... in v3_server.go.

graph TD
    cfg[embed.Config] --> embed[embed.Etcd]
    embed --> store[storage stack]
    embed --> raft[raftNode]
    embed --> server[EtcdServer]
    embed --> grpc[grpc.Server]
    grpc --> v3rpc[server/etcdserver/api/v3rpc]
    v3rpc --> server
    server --> raft
    raft --> store
    server --> apply[apply pipeline]
    apply --> store
    apply --> lease[lease.lessor]
    apply --> auth[auth.authStore]

Modes

Member (default)

Started with no positional argument. All flags are member-related. See reference/configuration.md for a curated subset.

Gateway (etcd gateway start)

Source: server/etcdmain/gateway.go. A stateless TCP load balancer in front of a known set of endpoints (or DNS SRV-discovered ones). It does not parse gRPC; it only forwards bytes. Useful when clients can't be reconfigured to know all members.

gRPC proxy (etcd grpc-proxy start)

Source: server/etcdmain/grpc_proxy.go, with the heavy lifting in server/proxy/grpcproxy/. Multiplexes many client connections into a single upstream cluster connection, deduplicates watches, and caches reads. Great for large fleets connecting to a small etcd cluster.

Integration points

• Reads/writes WAL files under <data-dir>/member/wal/ (server/storage/wal/).
• Persists snapshots under <data-dir>/member/snap/ (server/etcdserver/api/snap/).
• Persists MVCC + cluster metadata in <data-dir>/member/snap/db (bbolt).
• Listens on --listen-client-urls (default http://localhost:2379) and --listen-peer-urls (http://localhost:2380).
• Talks to peers using rafthttp over the peer URLs.
• Exposes /health, /version, /metrics, /debug/pprof/* via etcdhttp.

Entry points for modification

• New flag → server/embed/config.go (Config struct, parse()), then propagate to server/etcdserver/api/v3rpc/ or server/etcdserver/server.go as needed.
• New gRPC method → add to api/etcdserverpb/rpc.proto, regenerate (scripts/genproto.sh), implement in server/etcdserver/api/v3rpc/, wire to EtcdServer in v3_server.go.
• New apply behavior → server/etcdserver/apply/uber_applier.go and the per-op files in the same directory.

For storage and protocol-level concerns see systems/.