Architecture

etcd is a single Go binary that runs as a member of a Raft cluster. Each member persists log entries to a write-ahead log on disk, applies committed entries into a local MVCC key-value store backed by bbolt, and serves clients over gRPC and HTTP.

High-level layout

graph TD
    subgraph clients[Clients]
        cli[etcdctl / etcdutl]
        sdk[client/v3 Go SDK]
        rest[grpc-gateway REST]
    end

    subgraph member[etcd member process]
        embed[server/embed.Etcd]
        v3rpc[etcdserver/api/v3rpc]
        srv[etcdserver.EtcdServer]
        apply[etcdserver/apply]
        raftN[etcdserver.raftNode]
        rafthttp[etcdserver/api/rafthttp]
        mvcc[storage/mvcc]
        backend[storage/backend bbolt]
        wal[storage/wal]
        snap[etcdserver/api/snap]
        lease[server/lease]
        auth[server/auth]
    end

    cli -->|gRPC| v3rpc
    sdk -->|gRPC| v3rpc
    rest -->|HTTP/JSON| v3rpc
    v3rpc --> srv
    srv -->|propose| raftN
    raftN -->|peer messages| rafthttp
    rafthttp <-->|peer URLs| othermember[Other members]
    raftN -->|append| wal
    raftN -->|periodic| snap
    raftN -->|toApply| apply
    apply --> mvcc
    apply --> lease
    apply --> auth
    mvcc --> backend

The arrows show the dominant data flow for a write: a client sends a gRPC request, the v3 RPC layer forwards it through EtcdServer.Put/Range/Txn, which proposes a raft entry. Once the entry is committed by quorum, raftNode hands it to the apply package, which executes the operation against MVCC, leases, and auth.

Major subsystems and where they live

Subsystem	Location	One-liner
Server entry point	server/etcdmain/etcd.go	Parses flags, picks between server / gateway / proxy mode
Embedded server	server/embed/etcd.go, server/embed/config.go	Public Go API to run etcd in-process
etcd server core	server/etcdserver/server.go, server/etcdserver/v3_server.go	EtcdServer orchestrates Raft, MVCC, leases, auth
Raft node wrapper	server/etcdserver/raft.go	Drives go.etcd.io/raft/v3, owns Ready loop
Apply pipeline	server/etcdserver/apply/	Applies committed entries; transactions, conf changes
Peer transport	server/etcdserver/api/rafthttp/	HTTP-based Raft message and snapshot transport
gRPC RPC server	server/etcdserver/api/v3rpc/	Implements KV, Watch, Lease, Auth, Cluster, Maintenance services
HTTP/health/metrics	server/etcdserver/api/etcdhttp/	/health, /metrics, /version, debug endpoints
Membership	server/etcdserver/api/membership/	Cluster member roster, learner promotion
Snapshot store	server/etcdserver/api/snap/	Reads/writes raft snapshots on disk
Discovery	server/etcdserver/api/v3discovery/	Bootstrap via DNS/discovery URL
MVCC store	server/storage/mvcc/	Multi-version key-value store, watchers
Backend (bbolt)	server/storage/backend/	Boltdb wrapper, batched transactions
WAL	server/storage/wal/	Append-only write-ahead log, fsync, repair
Schema	server/storage/schema/	Bolt buckets, version/migration logic
Lease	server/lease/	TTL-based leases, expiration heap, checkpoints
Auth	server/auth/	RBAC users/roles/permissions, JWT/simple tokens
Compactor	server/etcdserver/api/v3compactor/	Periodic / revision-based history compaction
Watch cache	cache/	Optional buffered watch fan-out
Proxy modes	server/etcdmain/grpc_proxy.go, server/proxy/grpcproxy/, server/proxy/tcpproxy/	gRPC and L4 proxy modes
Public protobuf	api/etcdserverpb/, api/mvccpb/, api/authpb/, api/membershippb/	Wire-format definitions
Go client	client/v3/, client/pkg/	Official client SDK
CLI clients	etcdctl/, etcdutl/	User-facing command line tools
Common utilities	pkg/	Reusable helpers (flags, scheduler, traceutil, ...)
Tests	tests/integration/, tests/e2e/, tests/robustness/, tests/framework/	Multi-tier test suites
Tools	tools/benchmark/, tools/etcd-dump-*, tools/local-tester/	Internal dev/ops tools
Sample integrations	contrib/lock/, contrib/raftexample/, contrib/mixin/, contrib/systemd/	Example apps and operator configs

Write workflow (leader)

sequenceDiagram
    participant Client
    participant V3rpc as v3rpc.kvServer
    participant Server as EtcdServer
    participant Raft as raftNode
    participant WAL
    participant Apply
    participant MVCC

    Client->>V3rpc: Put(key, value)
    V3rpc->>Server: Put RPC
    Server->>Raft: Propose(entry)
    Raft->>WAL: Save(entries, hardstate)
    Raft-->>Raft: Commit on quorum
    Raft->>Apply: toApply(entries)
    Apply->>MVCC: Put → backend.BatchTx
    MVCC-->>Apply: revision
    Apply-->>Server: response
    Server-->>V3rpc: PutResponse
    V3rpc-->>Client: ok

A follower follows the same flow except the leader proposes on its behalf; the follower only persists and applies. See Documentation/etcd-internals/diagrams/write_workflow_leader.png and write_workflow_follower.png for the canonical diagrams maintained by the project.

Read workflow

Linearizable reads use ReadIndex to confirm leadership before serving data from MVCC. Serializable reads (WithSerializable() on the client side) skip Raft and read directly from the local MVCC view. The dispatch happens in server/etcdserver/v3_server.go and server/etcdserver/read/.

Module layout (Go workspace)

graph LR
    api[api/<br>protobuf, version]
    clientpkg[client/pkg/<br>fileutil, transport, types]
    clientv3[client/v3/<br>Go SDK]
    pkg[pkg/<br>generic helpers]
    server[server/<br>etcd binary core]
    cache[cache/<br>watch fan-out cache]
    etcdctl[etcdctl/<br>v3 CLI]
    etcdutl[etcdutl/<br>offline utility CLI]
    tests[tests/<br>integration, e2e, robustness]
    tools[tools/<br>benchmark, dump, mod]

    server --> api
    server --> clientpkg
    server --> pkg
    clientv3 --> api
    clientv3 --> clientpkg
    cache --> clientv3
    etcdctl --> clientv3
    etcdctl --> pkg
    etcdutl --> server
    tests --> server
    tests --> clientv3
    tools --> clientv3

Process modes

Beyond the normal cluster member, the same etcd binary supports:

• gateway mode (server/etcdmain/gateway.go) — a stateless TCP load balancer that forwards client traffic to a set of etcd endpoints discovered via DNS SRV.
• grpc-proxy mode (server/etcdmain/grpc_proxy.go, server/proxy/grpcproxy/) — a caching gRPC proxy that consolidates watches and key reads for clients that prefer to connect to a single endpoint.

Together with etcdctl and etcdutl, these are documented in applications/.