LinuxCommandLibrary

etcd

Distributed key-value store for configuration, service discovery

TLDR

Start a single-node etcd cluster

$ etcd
copy

Start a single-node etcd cluster, listening for client requests on a custom URL
$ etcd --advertise-client-urls [http://127.0.0.1:1234] --listen-client-urls [http://127.0.0.1:1234]
copy

Start a single-node etcd cluster with a custom name
$ etcd --name [my_etcd_cluster]
copy

Start a single-node etcd cluster with extensive metrics available at
$ etcd --enable-pprof --metrics extensive
copy

SYNOPSIS

etcd [options]

Example for bootstrapping a new 3-node etcd cluster:
etcd \
--name \
--data-dir /var/lib/etcd \
--initial-advertise-peer-urls http://:2380 \
--listen-peer-urls http://0.0.0.0:2380 \
--listen-client-urls http://0.0.0.0:2379 \
--advertise-client-urls http://:2379 \
--initial-cluster-token etcd-cluster-1 \
--initial-cluster node1=http://:2380,node2=http://:2380,node3=http://:2380 \
--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.

SEE ALSO

etcdctl(1), kubernetes, consul(1), zookeeper(1)

Copied to clipboard