etcd: A Distributed Key-Value Store Built for Critical Configuration Data

What etcd Is Designed For

etcd is a distributed key-value store for the most critical data of a distributed system. The README names four design properties: simple, secure, fast, and reliable. Simple refers to the gRPC API surface. Secure means automatic TLS with optional client certificate authentication. Fast refers to the 10,000 writes per second figure stated in the README. Reliable means the use of the Raft consensus algorithm to manage a highly available replicated log. The target use cases are the applications listed in the README as examples: Kubernetes stores all cluster state in etcd, locksmith uses it for coreos update coordination, vulcand uses it for proxy configuration, and Doorman uses it for distributed resource management. The common thread is that these applications need a store where writes are durable across failures and reads reflect the most recently committed state, even if multiple nodes in the cluster are involved in serving the answer. General-purpose caching, session storage, or ephemeral working data are not what etcd is optimized for. The watch API is central to many use cases: a client registers a watch on a key or key prefix, and etcd notifies the client whenever a matching key changes. This is what Kubernetes uses to detect pod state transitions and configuration changes without polling. The watch notifications carry the revision number of the change, which allows clients to detect missed events and re-read the current state after a reconnect without losing consistency.

How Raft Consensus Works in etcd

etcd uses the Raft consensus algorithm to keep data consistent across a cluster of nodes. In Raft, one node is elected leader and all writes go through the leader. The leader appends each write to its log and sends the entry to follower nodes. A write is committed only after a majority of nodes (a quorum) have acknowledged the entry. The go.mod file shows etcd depends on go.etcd.io/raft/v3 at v3.7.0, the Raft library maintained separately within the etcd organization. This consensus model means etcd trades write throughput for consistency: every write requires network round trips to a majority of nodes before the response is returned to the client. Read requests can go to the leader or, with linearizable read configured, require a quorum confirmation as well. The repository includes a robustness testing suite at tests/robustness/ that is referenced in the README alongside the production deployments, reflecting the emphasis on correctness over performance claims. A cluster of three nodes tolerates one node failure; a cluster of five tolerates two. This is the standard Raft quorum model, and it means that running a single etcd instance provides no fault tolerance at all. The GOVERNANCE.md file in the repository root documents the project's governance structure, and the community meeting schedule in the README reflects ongoing coordination between maintainers, which matters for teams evaluating the project's long-term viability for production infrastructure.

Installing etcd and Running Basic Commands

Pre-built release binaries for OSX, Linux, Windows, and Docker are available on the GitHub releases page. After downloading and extracting:

mv /tmp/etcd-download-test/etcd /usr/local/bin/
etcd

This starts a single-member cluster listening on port 2379 for client communication and port 2380 for server-to-server communication. To write and retrieve a key using etcdctl:

etcdctl put mykey "this is awesome"
etcdctl get mykey

For a three-node local cluster, install goreman and use the Procfile included in the repository:

goreman start

This starts three etcd members (infra1, infra2, infra3) and optionally an etcd grpc-proxy. To install the Go client library for embedding etcd access in a Go application:

go get go.etcd.io/etcd/client/v3

The official ports 2379 and 2380 are registered with IANA. The Dockerfile in the repository exposes both ports and starts etcd with CMD ["/usr/local/bin/etcd"].

The etcdctl and etcdutl Command-Line Tools

etcd ships with two command-line tools. etcdctl is the primary client for interacting with a running etcd cluster: it puts and gets keys, watches for changes, manages leases, handles authentication, and inspects cluster health. etcdutl is a utility for offline operations on etcd database files: it is used for data migration, snapshot restoration, and defragmentation outside of a running cluster. Both tools are built into the same release binary set and are included in the Dockerfile. The etcdctl source is in the etcdctl/ directory of the repository, and etcdutl is in the etcdutl/ directory. The repository also provides API documentation for the gRPC API at go.etcd.io/etcd/api/v3, the client library at go.etcd.io/etcd/client/v3, and the server at go.etcd.io/etcd/server/v3, all listed in the README's documentation section.

TLS, Authentication, and Security Configuration

etcd supports automatic TLS, and the README lists secure as one of the four core properties with optional client certificate authentication. The etcd.conf.yml.sample file in the repository root provides a reference configuration including TLS settings. The THREAT_MODEL.md file documents the known threat model and security assumptions. The security/ directory in the repository contains additional security-related documentation. A SECURITY.md file covers vulnerability disclosure. etcd's go.mod dependencies include golang-jwt/jwt for JWT-based authentication, reflecting the authentication system built into the server. For production deployments, the documentation at etcd.io/docs/latest/op-guide/security covers certificate generation, peer-to-peer TLS, and client-to-server TLS configuration. The repository's CodeQL analysis and OpenSSF Scorecard badges in the README reflect ongoing security scanning practices.

etcd Versus Redis for Distributed Coordination

The question of etcd versus Redis for distributed coordination comes up frequently because both can store key-value data accessible to multiple processes. The distinction is the consistency model. etcd is built on Raft and provides strong consistency by default: a successful write means a majority of cluster nodes have persisted the entry, and reads reflect the most recently committed state. Redis, in its single-instance form, provides no distributed consensus. Redis Cluster provides horizontal scaling but uses eventual consistency for cross-node coordination, not strong consistency. etcd's watch mechanism notifies clients of key changes with strong ordering guarantees, making it suitable for leader election and distributed locks where it is important to know exactly which change happened and in what order. Redis Sentinel and Redis Cluster provide high availability but the guarantees are different from Raft-based consensus. etcd's write throughput ceiling (10,000 writes/second as benchmarked in the README) is lower than Redis's, but that trade-off is intentional: etcd is not designed for high-volume data operations.

Versioning, Maintenance, and Licensing

etcd follows a versioned release model with parallel active release branches. The three most recent releases are v3.7.2, v3.6.15, and v3.5.34, all published on September 22, 2026, showing maintenance of three concurrent release series simultaneously. The go.mod shows the main module at v3 with internal sub-modules for api/, client/pkg, client/v3, etcdctl, etcdutl, pkg, server, and tests. The go.work file at the repository root coordinates this multi-module workspace. The last push was on 2026-09-25. The main branch is noted in the README as potentially unstable during development; stable versions come from releases. etcd is Apache-2.0 licensed, which permits use in proprietary and commercial applications without copyleft requirements. Community meetings run every Thursday at 11:00 AM Pacific time, alternating between general community meetings and issue triage sessions, as documented in the README.

Editorial conclusion

etcd is the right choice for storing critical distributed configuration, service discovery records, and leader election state where consistency guarantees are mandatory. It is not a general-purpose cache or a high-throughput data store: the README itself benchmarks it at 10,000 writes per second, which is a design point optimized for correctness rather than volume. Engineers running Kubernetes already use etcd as its backing store. For new projects, verify that your use case requires strong consistency before choosing etcd over an eventually consistent alternative, and plan for the operational overhead of running a three-node or five-node cluster to achieve fault tolerance.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes