Fun facts

A small grab-bag of curiosities you'll find while spelunking through the repo.

The oldest commit is older than gRPC etcd

The very first commit, 20ca21a3f on 2013-06-06, predates the gRPC v3 protocol by three years. It lays down a store module and unit test for store — the radix-tree v2 key-value store. Most of that early code is now gone, but server/etcdserver/api/v2store/ still ships as a vestigial sibling next to its v3 successors.

etcd's largest source file is 24,822 lines long

api/etcdserverpb/rpc.pb.go weighs in at 24,822 lines. It is, of course, generated by protoc from api/etcdserverpb/rpc.proto (1,458 lines of .proto source). The next four largest files are also generated. The biggest hand-written file is server/etcdserver/server.go at 2,476 lines.

etcd has both an etcdctl and an etcdutl

Two CLIs ship from this repo:

• etcdctl (etcdctl/) talks to a running cluster over gRPC.
• etcdutl (etcdutl/) operates on data files (snapshot DBs, WAL files) without ever connecting to a cluster.

The names differ by exactly one letter, which has caused regular confusion in issues. etcdutl was split out late in v3.5 to let operators do offline forensics without dragging in client libraries.

Why "etcd"?

Per the original CoreOS naming, "etcd" combines the Linux /etc directory (where machine configuration lives) with d for "distributed". The xkcd reliability tribute embedded in README.md (logos/etcd-xkcd-2347.png) is a knowing nod that the project sits at the bottom of many other systems' dependency stacks.

TODOs are persistent

A grep -rE "TODO|FIXME|HACK" --include="*.go" over the source tree finds 441 occurrences across 196 files. Some of the comments are old enough to vote.

The Procfile assumes you have goreman

The on-repo "local cluster" (Procfile) launches three nodes on ports :2379/12380, :22379/22380, :32379/32380. It is fed to goreman, a Procfile runner the project quietly depends on for its own dev loop:

goreman start

A learner member (port :42379/42380) is preconfigured but commented out, with promotion instructions in the same file.

The repository is a Go workspace, not a single module

go.work declares 11 modules at the repo root: ./, ./api, ./cache, ./client/pkg, ./client/v3, ./etcdctl, ./etcdutl, ./pkg, ./server, ./tests, ./tools/mod, ./tools/rw-heatmaps, ./tools/testgrid-analysis. Each tags independently (e.g. client/v3.6.10 is a real git tag). This split is recent in the project's lifetime — see lore.md for the migration story.

A library Raft, an integration Raft

The Raft implementation that powers etcd lives in a different repo: go.etcd.io/raft/v3. This repo only contains the integration layer — server/etcdserver/raft.go (the Ready loop) and server/etcdserver/api/rafthttp/ (the wire transport). That separation is why the raft/ directory you might expect to find here is not present.

etcd's robustness tests can break themselves on purpose

tests/robustness/ runs full clusters, hammers them with traffic, injects faults via gofail-driven failpoints (tests/robustness/failpoint/), and validates the resulting history is linearizable using a Porcupine-derived checker (tests/robustness/validate/). The test code itself is approaching the size of some of etcd's runtime subsystems.