etcd — Overview#

Identity#

• Module path: go.etcd.io/etcd/v3 (root workspace module)
• Go version: 1.26 (toolchain go1.26.1 — bleeding edge)
• License: Apache 2.0
• Repository: https://github.com/etcd-io/etcd

Purpose#

etcd is a distributed, reliable key-value store designed for the most critical data in distributed systems. It solves the consensus and coordination problem for distributed infrastructure: storing cluster configuration, service discovery records, and distributed locks with strong consistency guarantees via the Raft consensus algorithm. Its primary users are operators running distributed systems who need a reliable source of truth — most prominently, every Kubernetes cluster in existence.

Significance#

etcd is foundational cloud-native infrastructure: all Kubernetes clusters use etcd as their primary data store, making its user base effectively the entire Kubernetes ecosystem (which includes Pokémon Go, Salesforce, Ticketmaster, Box, and countless others). It is a CNCF project and one of the most battle-tested Go programs in production. Its design priorities — simplicity, security (TLS everywhere), speed (10,000 writes/sec), and reliability — have influenced how the Go ecosystem thinks about distributed systems programming. The Raft implementation was originally embedded but has been extracted into a standalone go.etcd.io/raft/v3 module, making it reusable by the wider community.

Key metrics#

• Go files: 1,099 (size tier L)
• Workspace modules (go.mod files): 13
  • api/ — protobuf-generated API types and gRPC definitions
  • cache/ — client-side caching layer
  • client/pkg/ — shared client utilities (TLS, transport, URLs)
  • client/v3/ — the public Go client library
  • etcdctl/ — command-line client tool
  • etcdutl/ — offline utility tool (snapshot inspection, migration)
  • pkg/ — shared internal utilities (wait groups, interval trees, etc.)
  • server/ — the etcd server itself (core engine)
  • tests/ — integration, e2e, and robustness test suite
  • tools/mod/ — tool dependencies
  • tools/rw-heatmaps/ — benchmarking visualization tool
  • tools/testgrid-analysis/ — CI analysis tool
  • Root workspace module (wires everything together)
• Top-level directories: api, cache, client, contrib, etcdctl, etcdutl, pkg, server, tests, tools, hack, Documentation, CHANGELOG
• Direct dependencies (root go.mod): 21
• go.sum entries: 214
• Key external dependencies: go.etcd.io/bbolt (storage), go.etcd.io/raft/v3 (consensus), google.golang.org/grpc, go.uber.org/zap, github.com/spf13/cobra, OpenTelemetry stack

Notable characteristics#

• Multi-module Go workspace: etcd is organized as a Go workspace with 13 distinct modules, enforcing clean API boundaries between the server, client library, CLI tools, and test infrastructure. This means consumers can depend on client/v3 without pulling in server-side dependencies.
• Extracted Raft module: The Raft consensus implementation lives in a separate repository (go.etcd.io/raft/v3), making it independently usable. This is architecturally significant — the protocol layer is cleanly separated from the application layer.
• gRPC-first API with REST gateway: The entire client/server API is defined in Protocol Buffer files (api/etcdserverpb/rpc.proto), served over gRPC, with a grpc-gateway providing a REST/JSON proxy. This makes the API strongly typed and language-agnostic.
• Correctness over convenience: The codebase includes a dedicated tests/robustness/ suite using Jepsen-style linearizability checking, reflecting the project’s strong emphasis on verifiable correctness. There is also an antithesis test template for chaos engineering.
• Security as a first-class concern: TLS is automatic and the server/auth/ package implements RBAC (role-based access control) with JWT token support (github.com/golang-jwt/jwt/v5). The project publishes a security disclosure process in security/README.md.
• MVCC storage engine: The server/storage/mvcc/ package implements a multi-version concurrency control store on top of bbolt, enabling watch functionality (clients can watch for changes to any key range) and historical revisions — a distinctive capability versus simpler key-value stores.