etcd
Distributed key-value store for configuration, service discovery
TLDR
Start a single-node etcd cluster
Start a single-node etcd cluster, listening for client requests on a custom URL
Start a single-node etcd cluster with a custom name
Start a single-node etcd cluster with extensive metrics available at
SYNOPSIS
etcd [options]
Example for bootstrapping a new 3-node etcd cluster:
etcd \
--name
--data-dir /var/lib/etcd \
--initial-advertise-peer-urls http://
--listen-peer-urls http://0.0.0.0:2380 \
--listen-client-urls http://0.0.0.0:2379 \
--advertise-client-urls http://
--initial-cluster-token etcd-cluster-1 \
--initial-cluster node1=http://
--initial-cluster-state new
PARAMETERS
--name
Human-readable name for this etcd member. Must be unique within the cluster.
--data-dir
Path to the data directory where etcd stores its persistent data (WAL, snapshots).
--wal-dir
Path to a dedicated WAL (Write Ahead Log) directory. Recommended for performance and durability.
--listen-peer-urls
List of URLs etcd listens on for peer (member-to-member) communication. For example: http://0.0.0.0:2380.
--listen-client-urls
List of URLs etcd listens on for client communication (e.g., from etcdctl or applications). For example: http://0.0.0.0:2379.
--advertise-client-urls
List of URLs to advertise to clients so they can connect to this etcd member. Should be publicly accessible.
--initial-advertise-peer-urls
List of URLs to advertise to the other members of the cluster. Used during cluster bootstrapping.
--initial-cluster-token
Unique token for the new cluster. Helps prevent accidental cluster formation or misconfiguration.
--initial-cluster
Initial cluster configuration for a new cluster or when joining an existing one. Format:
--initial-cluster-state
Initial cluster state. Use new for bootstrapping a new cluster, existing for joining an existing one.
--client-cert-auth
Enable client certificate authentication for client connections, enhancing security.
--peer-client-cert-auth
Enable peer client certificate authentication for peer connections, ensuring secure member-to-member communication.
--trusted-ca-file
Path to the client CA file used for verifying client certificates.
--peer-trusted-ca-file
Path to the peer CA file used for verifying peer certificates.
DESCRIPTION
etcd is a distributed, reliable, and consistent key-value store designed for shared configuration, service discovery, and coordinating distributed systems. It acts as a highly available backing store for applications that need to maintain state or synchronize access across a cluster of machines.
It employs the Raft consensus algorithm to ensure data consistency and fault tolerance across its members, making it resilient to node failures. etcd is widely used in cloud-native environments, most notably as the primary datastore for Kubernetes clusters, storing all cluster state and configuration. It provides a simple HTTP/gRPC API for programmatic interaction.
CAVEATS
etcd requires a quorum (majority of members) to be available for writes and many reads. Losing quorum renders the cluster unavailable for writes until a quorum is restored.
Its performance is highly dependent on fast disk I/O (especially for the WAL) and low network latency between members.
Backup and restore procedures are critical for disaster recovery. It's recommended to run an odd number of members (e.g., 3, 5, or 7) for fault tolerance and to simplify quorum management.
DATA MODEL
etcd organizes data as a hierarchical key-value store, where keys are paths (e.g., /config/service/setting). It supports basic CRUD (Create, Read, Update, Delete) operations and advanced features like watches, allowing clients to subscribe to changes on specific keys or prefixes, enabling real-time updates.
CONSISTENCY MODEL
etcd enforces strong consistency (linearizability) across all members of a cluster using the Raft consensus algorithm. This guarantees that all operations appear to occur atomically and in a single, well-defined global order, providing a predictable and reliable foundation for building distributed applications.
HISTORY
etcd was originally developed by CoreOS (later acquired by Red Hat/IBM) and first released in 2013. It was created to provide a more robust and simpler distributed key-value store compared to existing solutions like ZooKeeper, focusing on modern distributed systems challenges. Its adoption significantly grew with the rise of Kubernetes, for which it serves as the foundational data store, managing all cluster state and configuration.