ConfigsApr 11, 2026·1 min read

etcd — Distributed Reliable Key-Value Store for Critical Data

etcd is a strongly consistent, distributed key-value store for configuration, service discovery, and coordination. Uses the Raft consensus algorithm. Powers Kubernetes, OpenShift, CoreOS, and many other distributed systems.

AI
AI Open Source · Community
Quick Use

Use it first, then decide how deep to go

This block should tell both the user and the agent what to copy, install, and apply first.

# Install
brew install etcd                          # macOS
sudo apt install etcd                      # Debian/Ubuntu
docker run -d --name etcd -p 2379:2379 -p 2380:2380 \
  quay.io/coreos/etcd:v3.5.15 \
  /usr/local/bin/etcd \
  --listen-client-urls http://0.0.0.0:2379 \
  --advertise-client-urls http://localhost:2379

CLI usage:

export ETCDCTL_API=3

etcdctl put /config/db/host "postgres.internal"
etcdctl get /config/db/host
etcdctl get /config --prefix
etcdctl del /config/db/host
etcdctl watch /config --prefix

# Transactions
etcdctl txn -i

# Leases (TTL)
LEASE_ID=$(etcdctl lease grant 60 | awk "{print \$2}")
etcdctl put --lease=$LEASE_ID /services/web "host:8080"

# Member operations
etcdctl member list
etcdctl endpoint health
etcdctl endpoint status --cluster -w table
Intro

etcd is a strongly consistent, distributed key-value store providing a reliable way to store data across a cluster of machines. It uses the Raft consensus algorithm for leader election and log replication. Originally built for CoreOS; now a graduated CNCF project powering Kubernetes as its primary datastore.

What etcd Does

  • Distributed KV — reliable storage with strong consistency
  • Raft consensus — leader election and log replication
  • Watches — subscribe to key changes in real time
  • Leases — TTL-based key expiration
  • Transactions — atomic multi-key compare-and-swap
  • MVCC — multi-version concurrency control, historic reads
  • gRPC API — binary protocol for performance
  • Dynamic reconfiguration — add/remove members at runtime

Architecture

A cluster of 3 or 5 etcd members runs the Raft protocol. One is elected leader, others are followers. Writes go through the leader and are replicated. Reads can be linearizable (through leader) or serializable (local). Key revisions use MVCC.

Self-Hosting

# 3-node cluster
etcd --name infra1 --initial-advertise-peer-urls http://10.0.1.10:2380 \
     --listen-peer-urls http://10.0.1.10:2380 \
     --listen-client-urls http://10.0.1.10:2379,http://127.0.0.1:2379 \
     --advertise-client-urls http://10.0.1.10:2379 \
     --initial-cluster-token etcd-cluster-1 \
     --initial-cluster infra1=http://10.0.1.10:2380,infra2=http://10.0.1.11:2380,infra3=http://10.0.1.12:2380 \
     --initial-cluster-state new

Key Features

  • Strong consistency (Raft)
  • Watches for change notifications
  • Lease TTLs
  • MVCC historical reads
  • Transactions (compare-and-swap)
  • Role-based access control
  • TLS encryption
  • Dynamic cluster reconfiguration
  • gRPC client protocol

Comparison

Store Consistency Use Case
etcd Strong (Raft) Config, K8s state
Consul Strong (Raft) Service discovery + KV
ZooKeeper Strong (ZAB) Coordination (legacy)
Redis Eventual (cluster) Cache, queues
TiKV Strong (Raft) Transactional KV store

常见问题 FAQ

Q: 集群要几个节点? A: 奇数(3、5、7)以形成多数派。3 节点容忍 1 故障,5 容忍 2。更多节点写入延迟增加。

Q: etcd vs Consul? A: etcd 专注 KV + 强一致;Consul 功能更广(服务发现、健康检查、服务网格)。K8s 用 etcd 因为只需要可靠 KV。

Q: 数据上限? A: 默认 2GB,可调到 8GB。超过建议分 namespace 或用其他方案。etcd 不是通用数据库。

来源与致谢 Sources

Discussion

Sign in to join the discussion.
No comments yet. Be the first to share your thoughts.

Related Assets