Lore

A timeline of how etcd became what it is. Dates are derived from git tags and the first commits to relevant directories.

Eras

CoreOS roots (Jun 2013 – mid 2014)

The project was started inside CoreOS. The very first commit, 20ca21a3f on 2013-06-06, lays down the original store module: an in-memory radix-tree key-value store with HTTP/JSON access. Early etcd (v0.x – v2.x) was a different beast from today's etcd: HTTP/JSON, a custom Raft implementation, and a node-based hierarchical key space.

v2 stable era and the "raft library" split (2014 – 2016)

By v2.0, etcd had been adopted by Kubernetes (which initially used the v2 API) and the Raft implementation had been generalized into a reusable library. That library now lives outside this repository at go.etcd.io/raft; this repo keeps only the integration layer in server/etcdserver/raft.go and server/etcdserver/api/rafthttp/.

The v3 protocol rewrite (Jun 2016)

v3.0.0 tagged on 2016-06-30. v3 replaced the JSON-over-HTTP API with gRPC + protobuf, introduced MVCC (server/storage/mvcc/), revisions, watches that survive restarts, and leases. The legacy v2 store hung around for cluster metadata for several more releases. Every subsystem you read about in this wiki was either born in or rewritten for v3.

The v2 → v3 transition is still visible in the source tree:

• server/etcdserver/api/v2store/, v2error/, v2stats/ — leftover v2 surfaces
• etcdctl/READMEv2.md — v2 CLI documentation
• api/etcdserverpb/etcdserver.proto — small remaining v2-style request type

Steady stabilization (2017 – 2019)

The 3.1 → 3.4 releases (Jan 2017 – Aug 2019) focused on hardening: improved snapshot/restore, learner members (3.4), gRPC proxy, JWT auth tokens, distributed tracing hooks, and a long parade of metrics. v3.4.0 (2019-08-30) is the version most large Kubernetes deployments standardized on for years.

v3.5 and the silent-corruption postmortem (Jun 2021 – 2023)

v3.5.0 shipped on 2021-06-15 with a major reorganization: the project moved from a single Go module to a multi-module Go workspace (the structure you see today in go.work), and the release added structured logging via zap by default. Shortly after release, the community discovered a data inconsistency bug under specific failure scenarios; the fix and the broader response is captured in Documentation/postmortems/.

That postmortem catalyzed two long-running investments:

1. Robustness testing: the tests/robustness/ directory grew into a comprehensive linearizability + fault-injection harness, today one of the largest test trees in the repo.
2. Antithesis integration: deterministic-simulation testing scaffolding under tests/antithesis/ and .github/workflows/antithesis-*.yml.

The long road to v3.6 (2021 – May 2025)

The gap between 3.5.0 and 3.6.0 ran almost four years — the project's longest. v3.6 ultimately tagged on 2025-05-15, introducing among other things:

• A reworked server/etcdserver/apply/ package (uber_applier.go, auth.go, corrupt.go, ...).
• A new top-level cache/ module (added in 2025) for buffered watch fan-out.
• The Go-workspace migration completed; per-module tags (server/v3.6.0, client/v3.6.0, etcdctl/v3.6.0, etc.) replace the old single-module versioning.
• A pkg/featuregate/ registry mirroring Kubernetes' feature-gate model and server/features/ to declare gates per binary.
• A new server/storage/schema/migration.go machinery for forward/backward schema migrations on the bolt buckets.

v3.6.x maintenance and 3.7 / 4.0 planning (2025 – present)

CHANGELOG/CHANGELOG-3.6.md, CHANGELOG-3.7.md, and CHANGELOG-4.0.md exist side by side at the time of writing. v3.6 minor releases continue (most recently v3.6.10) while design discussions for 3.7 / 4.0 percolate. Recent commits at wiki time were focused on RBAC bypass fixes (PRs #21677, #21680, #21689) and etcdutl polish (#21686).

Longest-standing features

Feature	First introduced	Notes
server/storage/wal/ (write-ahead log)	2014	The fundamental durability layer; format has evolved (CRC, version markers in version.go) but the package boundary is original.
server/storage/mvcc/ (MVCC store)	v3.0 (2016)	Revision arithmetic and the key_index data structure are largely as designed in 2015–2016.
server/lease/ (leases)	v3.0 (2016)	Lease heap, checkpointing added later.
etcdctl/ctlv3/	v3.0 (2016)	The Cobra-based v3 CLI.
client/v3/	v3.0 (2016)	The official Go client interface (KV, Watcher, Lessor, Auth, Maintenance) has been remarkably stable.

Deprecated or removed features

Item	What	When
etcd v2 store	The radix-tree key store with HTTP/JSON. The protocol is gone; server/etcdserver/api/v2store/ only persists for backward-compatible cluster metadata.	Deprecated through 3.x; many references removed pre-3.6.
clientv2	The v2 Go client.	Removed in the 3.5 timeframe; only references remain in etcdctl/READMEv2.md.
etcd-runner / functional test suite	A long-running, network-fault testing tool replaced by the new tests/robustness/ and Antithesis-based suites.	Removed during 3.6 development.
Single-module versioning	All packages tagged vX.Y.Z from the repo root.	Replaced by per-module tags (server/, api/, client/v3/, ...) starting with the workspace migration in 3.5.
raft source in this repo	The Raft library code.	Moved to go.etcd.io/raft (separate repo) prior to 3.6.

Major rewrites and migrations

• HTTP/JSON → gRPC + protobuf (v3.0).
• Single Go module → Go workspace with multiple modules (v3.5 timeframe; finalized for v3.6).
• logger (capnslog) → zap (v3.5+).
• Apply pipeline refactor: introduction of server/etcdserver/apply/uber_applier.go consolidating the previously scattered apply paths (3.6).
• Schema migration framework: server/storage/schema/migration.go enables clean forward/backward bolt-bucket evolution (3.6).
• Robustness suite: tests/robustness/ rebuilt after the 3.5 inconsistency incident.

Growth trajectory

• 2013-2016: founding period; one Go module, dual API surface (v2 + v3).
• 2017-2020: stabilization; CNCF graduation (Nov 2018), heavy Kubernetes co-evolution.
• 2021-2023: post-3.5 inconsistency response, robustness investment, governance moves.
• 2024-2026: workspace migration completes, v3.6 ships, Antithesis-based deterministic testing comes online, cache/ module appears.

For change-by-change detail, the per-version CHANGELOG/CHANGELOG-3.X.md files are the authoritative narrative.