etcd 3.7: The Raft-Based Key-Value Store That Holds Kubernetes Together

What etcd Solves and Who It Is For

etcd solves a narrow but painful problem: storing the small amount of data that a distributed system absolutely cannot lose or disagree about. This includes leader election state, configuration, service discovery records, and coordination locks. The README describes it as a store for "the most critical data of a distributed system," and it is famously paired with Kubernetes, locksmith, vulcand, and Doorman. The target audience is engineers running clustered applications that need a consistent, highly available source of truth. It is not a general-purpose database; it is a coordination primitive. If your data is ephemeral or can tolerate eventual consistency, etcd is overkill. But if your system must agree on a single value even when some nodes fail, etcd is designed for exactly that.

The Raft Mechanism: Replicated Log, Not Master-Slave

etcd's core mechanism is the Raft consensus algorithm, which the README says is used to "manage a highly-available replicated log." Every write goes to the leader, which appends it to its log and replicates it to a quorum of followers. Only after a majority acknowledges does the write commit. This ensures that even if a minority of nodes fail, the cluster can still make progress. The API is gRPC-based, which the README highlights as "well-defined, user-facing." The data model is a simple key-value store, but the consistency guarantees are what matter. etcd also supports watches and leases, though those are not detailed in the README. The trade-off is that every write incurs round-trips to multiple nodes, which is why the benchmark of 10,000 writes per second is a ceiling, not a typical number. For read-heavy workloads, etcd can serve reads from any member, but linearizable reads still require a round-trip to the leader.

Getting etcd Running: From Single Node to Local Cluster

The quickest start is to download a pre-built binary from the release page for OSX, Linux, Windows, or Docker. The README shows running the binary directly: `/tmp/etcd-download-test/etcd` or moving it to `/usr/local/bin/etcd` and then just `etcd`. That brings up a single-member cluster on port 2379 for client traffic and 2380 for peer communication. To test it, use `etcdctl put mykey "this is awesome"` and `etcdctl get mykey`. For a local multi-member cluster, the README recommends installing `goreman` and running `goreman start` from the repository root, which uses the Procfile to launch three members named infra1, infra2, and infra3, plus an optional gRPC proxy. The Procfile also has comments for adding a learner node, which is a non-voting member that catches up before joining the quorum. This is a practical way to experiment with failure scenarios without spinning up multiple machines.

The Cost of Reliability: Operational Complexity and Version Churn

etcd's reliability comes at a price. Running a production cluster means managing multiple members, handling network partitions, and tuning heartbeats and election timeouts. The README warns that the `main` branch "may be in an unstable or even broken state during development," which means you must pin to a release. The release cadence is active: v3.7.1, v3.6.14, and v3.5.33 were all pushed on the same day, showing that multiple minor versions are maintained simultaneously. This is good for stability but adds upgrade burden. Each minor version has its own quirks, and you need to read the release notes to know what changed. The README also mentions "rigorous robustness testing" but does not detail what it covers, so you cannot assume every failure mode is caught. If your team is not prepared to operate a distributed system, etcd will bite you. The wrong tool is a single-node deployment where you ignore the clustering requirements; you lose availability and risk split-brain if you ever try to add nodes later.

Alternatives: ZooKeeper and Consul Take Different Paths

The main alternatives to etcd are ZooKeeper and Consul, each with a different approach. ZooKeeper also uses a consensus algorithm (ZAB, not Raft) and exposes a hierarchical namespace, which is more natural for some coordination patterns like distributed locks. Its client API is older and more verbose, but it has a long track record in Hadoop and Kafka ecosystems. Consul, on the other hand, uses a gossip protocol for membership and Raft for consistency, but it bundles service discovery, health checking, and a DNS interface, which etcd does not provide out of the box. If you need those features, Consul is a more integrated solution. etcd's advantage is its simplicity: a pure key-value store with a clean gRPC API, which makes it a lower-level building block. The choice depends on whether you want a minimal core that you compose with other tools, or a fuller platform. Kubernetes chose etcd, so if you are already in that world, etcd is the natural fit.

Maintenance, Upgrades, and License Considerations

etcd is licensed under Apache-2.0, which permits commercial use, modification, and distribution, with the condition that you retain copyright notices. This is permissive, but you should still review the full license text for your specific use case. The project is maintained by a team that meets weekly, as noted in the README, and there are multiple release lines: v3.5, v3.6, and v3.7. The v3.5 line is likely the most battle-tested, given its long history of patch releases (v3.5.33). Upgrading between minor versions requires reading the migration guides, which are not in the README but are on the etcd website. The maintenance cost is real: you must monitor disk space, defragment the store periodically, and back up snapshots. The README does not cover these operational tasks, but they are standard for any Raft-based store. If you cannot commit to that operational discipline, consider a managed service or a simpler alternative.

Editorial conclusion

Adopt etcd if you need a battle-tested, Raft-based key-value store for configuration data, service discovery, or coordination in a distributed system, especially if you are already in the Kubernetes ecosystem. Do not adopt it if you need a general-purpose database with rich querying or if you cannot tolerate the operational overhead of managing a multi-member cluster. Before adopting, verify your required version's release notes and the robustness testing suite to understand current failure modes. Check the Apache-2.0 license implications for your use case. Start with a single-member cluster to learn the API, then scale to three or five members for production, and always configure TLS for client and peer communication.

Official sources

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