A Quick Guide to etcd: Introduction, Installation, Architecture, and Practical Usage

1. etcd Introduction

etcd, launched by CoreOS in 2013 and written in Go, is a distributed key‑value store that offers simple installation, HTTP API, hierarchical file‑like storage, watch mechanism, SSL security, high performance (2k/s reads), and strong consistency via the Raft consensus algorithm.

2. etcd Application Scenarios

etcd excels in stability, reliability, and scalability, making it ideal for service registration and discovery, key‑value storage, message publish/subscribe, and distributed locks.

2.1 Key‑Value Storage

etcd stores data as a hierarchical key‑value map, providing higher read/write performance than relational databases and supporting distributed replication across nodes.

2.2 Service Registration & Discovery

Services register their name, host, and port in etcd; clients query etcd to discover service endpoints, with TTL‑based health checks ensuring up‑to‑date information.

2.3 Message Publish & Subscribe

etcd can act as a lightweight message broker where producers publish to a topic and consumers subscribe to receive change events.

2.4 Distributed Locks

Using etcd’s atomic compare‑and‑swap API, applications can implement exclusive or ordered locks for coordinated resource access.

3. Installation Methods

etcd can be installed via package managers, binary releases, source compilation, or Docker containers.

3.1 Binary Installation (macOS example)

ETCD_VER=v3.4.5
GITHUB_URL=https://github.com/etcd-io/etcd/releases/download
DOWNLOAD_URL=${GITHUB_URL}

rm -f /tmp/etcd-${ETCD_VER}-darwin-amd64.zip
rm -rf /tmp/etcd-download-test && mkdir -p /tmp/etcd-download-test

curl -L ${DOWNLOAD_URL}/${ETCD_VER}/etcd-${ETCD_VER}-darwin-amd64.zip -o /tmp/etcd-${ETCD_VER}-darwin-amd64.zip
unzip /tmp/etcd-${ETCD_VER}-darwin-amd64.zip -d /tmp && rm -f /tmp/etcd-${ETCD_VER}-darwin-amd64.zip
mv /tmp/etcd-${ETCD_VER}-darwin-amd64/* /tmp/etcd-download-test && rm -rf /tmp/etcd-${ETCD_VER}-darwin-amd64

/tmp/etcd-download-test/etcd --version
/tmp/etcd-download-test/etcdctl version

The above script installs etcd 3.4.5 on macOS and verifies the version.

3.2 Source Installation

git clone https://github.com/etcd-io/etcd.git
cd etcd
./build

3.3 Docker Cluster Deployment

docker pull bitnami/etcd:3.4.7
docker image tag bitnami/etcd:3.4.7 quay.io/coreos/etcd:3.4.7

REGISTRY=quay.io/coreos/etcd
ETCD_VERSION=3.4.5
TOKEN=my-etcd-token
CLUSTER_STATE=new
NAME_1=etcd-node-0
HOST_1=192.168.202.128
CLUSTER=${NAME_1}=http://${HOST_1}:2380

docker run \
  -p 2379:2379 -p 2380:2380 \
  --volume=${DATA_DIR}:/etcd-data \
  --name etcd ${REGISTRY}:${ETCD_VERSION} \
  /usr/local/bin/etcd \
  --data-dir=/etcd-data --name ${NAME_1} \
  --initial-advertise-peer-urls http://${HOST_1}:2380 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --advertise-client-urls http://${HOST_1}:2379 \
  --listen-client-urls http://0.0.0.0:2379 \
  --initial-cluster ${CLUSTER} \
  --initial-cluster-state ${CLUSTER_STATE} --initial-cluster-token ${TOKEN}

3.4 Dynamic Discovery Cluster Startup

# etcd1 startup
/opt/etcd/bin/etcd \
  --name etcd1 \
  --initial-advertise-peer-urls http://192.168.202.128:2380 \
  --listen-peer-urls http://192.168.202.128:2380 \
  --data-dir /opt/etcd/data \
  --listen-client-urls http://192.168.202.128:2379,http://127.0.0.1:2379 \
  --advertise-client-urls http://192.168.202.128:2379 \
  --discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de

Similar commands are used for etcd2 and etcd3, allowing the cluster to self‑assemble once the discovery token size is satisfied.

4. etcd v3 Architecture

etcd v3 uses the Raft algorithm to maintain a quorum of (n+1)/2 nodes. A leader handles writes and replicates logs; if the leader fails, a new leader is elected. The data model is a simple ordered map of keys to values, with watch support for change notifications.

5. etcdctl Practical Usage

etcdctl is the command‑line client for interacting with etcd. It supports version selection (export ETCDCTL_API=2 or =3) and provides a rich set of commands for alarms, authentication, performance checks, compaction, defragmentation, key operations, leases, locks, snapshots, and more.

5.1 Common Commands

$ etcdctl version
etcdctl Version: 3.4.7

$ etcdctl put /testdir/key "Hello world"
$ etcdctl get /testdir/key
Hello world

$ etcdctl del foo --prev-kv
1
foo
val

5.2 Key Operations

Put: etcdctl put /path/key "value"

Get: etcdctl get /path/key (supports --prefix , --rev , --hex , --from-key )

Delete: etcdctl del /path/key (supports --prefix , --from-key )

Watch: etcdctl watch /path/key (supports --rev , --prev-kv , --hex )

5.3 Lease Management

$ etcdctl lease grant 100
lease 694d71ddacfda227 granted with TTL(100s)

$ etcdctl put --lease=694d71ddacfda227 foo10 bar
OK

$ etcdctl lease revoke 694d71ddacfda227
lease 694d71ddacfda227 revoked

6. Secure Operations (TLS/SSL)

etcd can secure peer and client communication using TLS certificates. The tutorial demonstrates generating a CA with cfssl, issuing server certificates, and starting an etcd cluster with --client-cert-auth , --trusted-ca-file , --cert-file , and --key-file flags.

# Generate CA
cfssl gencert -initca ca-csr.json | cfssljson -bare ca

# Generate server cert
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem -config=ca-config.json -profile=etcd server-csr.json | cfssljson -bare server

Cluster nodes are then started with TLS options pointing to the generated ca.pem , server.pem , and server-key.pem .

7. Conclusion

etcd provides a highly stable, reliable, and scalable key‑value store that underpins many cloud‑native systems. Understanding its installation, clustering modes, API usage, and security configuration enables developers to build robust distributed applications.