etcd CLI

etcdctl cheatsheet — get, put, delete keys, watch changes, manage cluster. etcdctl get /key, etcdctl put, etcdctl member list. Full etcd CLI reference.

9 min read

etcdctl

The official command-line client for etcd, used for interacting with and managing etcd clusters.

Installation

Linux:

# Download the latest release binary
ETCD_VER=v3.5.9 # Replace with the latest version
curl -L https://github.com/etcd-io/etcd/releases/download/${ETCD_VER}/etcd-${ETCD_VER}-linux-amd64.tar.gz -o etcd-${ETCD_VER}-linux-amd64.tar.gz
tar xzvf etcd-${ETCD_VER}-linux-amd64.tar.gz
sudo mv etcd-${ETCD_VER}-linux-amd64/etcdctl /usr/local/bin/
sudo mv etcd-${ETCD_VER}-linux-amd64/etcd /usr/local/bin/
rm -rf etcd-${ETCD_VER}-linux-amd64*

macOS:

# Download the latest release binary
ETCD_VER=v3.5.9 # Replace with the latest version
curl -L https://github.com/etcd-io/etcd/releases/download/${ETCD_VER}/etcd-${ETCD_VER}-darwin-amd64.zip -o etcd-${ETCD_VER}-darwin-amd64.zip
unzip etcd-${ETCD_VER}-darwin-amd64.zip
sudo mv etcd-${ETCD_VER}-darwin-amd64/etcdctl /usr/local/bin/
sudo mv etcd-${ETCD_VER}-darwin-amd64/etcd /usr/local/bin/
rm -rf etcd-${ETCD_VER}-darwin-amd64*

Windows: Download the appropriate .zip file from the etcd releases page and extract etcdctl.exe. Add its directory to your system’s PATH.

Core Concepts

  • Key-Value Store: etcd is a distributed consistent key-value store. Data is organized as keys, and each key has an associated value.
  • Lease: A lease is a mechanism to manage the time-to-live (TTL) of keys. When a lease expires, all keys associated with that lease are automatically deleted. This is useful for leader election and ephemeral data.
  • Watch: Clients can watch for changes on specific keys or key ranges. etcd will notify the client when modifications occur.
  • Transaction: etcd supports atomic compare-and-swap (CAS) operations, allowing for conditional updates to keys.

Configuration

Before using etcdctl, you need to configure it to connect to your etcd cluster. This is typically done using environment variables:

  • ETCDCTL_ENDPOINTS: A comma-separated list of etcd endpoint URLs (e.g., http://127.0.0.1:2379).
  • ETCDCTL_CACERT: Path to the CA certificate file for TLS verification.
  • ETCDCTL_CERT: Path to the client certificate file for TLS authentication.
  • ETCDCTL_KEY: Path to the client private key file for TLS authentication.

Example using environment variables:

export ETCDCTL_ENDPOINTS="http://localhost:2379"
export ETCDCTL_CACERT="/etc/etcd/ca.crt"
export ETCDCTL_CERT="/etc/etcd/client.crt"
export ETCDCTL_KEY="/etc/etcd/client.key"

Commands / Usage

Managing Keys and Values

Put a key-value pair:

etcdctl put mykey "myvalue"

Sets the value of mykey to myvalue.

Get the value of a key:

etcdctl get mykey

Retrieves the value associated with mykey.

Get a range of keys:

etcdctl get prefix-

Retrieves all keys that start with prefix-.

Delete a key:

etcdctl del mykey

Deletes mykey and its associated value.

Delete a range of keys:

etcdctl del prefix-

Deletes all keys that start with prefix-.

List all keys:

etcdctl member list

Lists all members of the etcd cluster. (This is a common mistake, member list is for cluster members, not keys). To list all keys, you often need to get a range that covers everything, or use a specific prefix if known.

Managing Leases

Create a lease with a TTL of 10 seconds:

etcdctl lease grant 10

Grants a new lease with ID X and TTL 10.

Keep a lease alive:

etcdctl lease keep-alive X # Replace X with the lease ID

Extends the TTL of lease X.

Revoke a lease:

etcdctl lease revoke X # Replace X with the lease ID

Immediately expires lease X.

Put a key with a lease:

etcdctl put mykey "myvalue" --lease=X # Replace X with the lease ID

Sets the value of mykey to myvalue, associated with lease X.

List leases:

etcdctl lease list

Lists all active leases.

Watching for Changes

Watch a specific key for changes:

etcdctl watch mykey

Blocks until mykey is created, updated, or deleted.

Watch a key range for changes:

etcdctl watch prefix-

Blocks until any key starting with prefix- is created, updated, or deleted.

Watch for all events (PUT, DELETE):

etcdctl watch --event-types=PUT,DELETE mykey

Watch only for PUT and DELETE events on mykey.

Watch with a revision:

etcdctl watch mykey --rev=12345

Starts watching mykey from revision 12345.

Transactions

Perform a conditional put:

etcdctl txn --key=/my/key --compare val="oldvalue" --then put /my/key "newvalue"

If /my/key currently has the value oldvalue, then set its value to newvalue.

Perform a conditional delete:

etcdctl txn --key=/my/key --compare val="value_to_delete" --then del /my/key

If /my/key has the value value_to_delete, then delete it.

Perform multiple operations in a transaction:

etcdctl txn --key=/key1 --compare val="v1" --then put /key2 "v2" --else put /key3 "v3"

If /key1 has value v1, then put v2 into /key2. Otherwise, put v3 into /key3.

Cluster Management

List cluster members:

etcdctl member list

Shows the IDs, status, names, peer URLs, and client URLs of all members in the cluster.

Add a new member to the cluster:

etcdctl member add new-member --peer-urls=http://new-member-ip:2380

Adds a new member named new-member with the specified peer URLs.

Remove a member from the cluster:

etcdctl member remove MEMBER_ID # Replace MEMBER_ID with the actual member ID

Removes the member with the given ID from the cluster.

Update a member’s peer URLs:

etcdctl member update MEMBER_ID --peer-urls=http://updated-ip:2380 # Replace MEMBER_ID

Updates the peer URLs for the specified member.

Cluster Health and Status

Check cluster health:

etcdctl endpoint health

Checks the health of all etcd endpoints.

Get cluster status:

etcdctl endpoint status --write-out=table

Shows detailed status information for each endpoint in a table format.

Get cluster version:

etcdctl version

Displays the etcd version for the client and all connected servers.

Alarm Management

List alarms:

etcdctl alarm list

Lists any active alarms on the cluster (e.g., disk or member failure).

Deactivate an alarm:

etcdctl alarm deactivate

Clears all active alarms. This should be done after resolving the underlying issue.

Compaction and Defragmentation

Compact the event history:

etcdctl compact X # Replace X with the revision number

Removes all events with revision numbers less than X. This reclaims space.

Defragment the database:

etcdctl defrag

Reclaims space in the etcd data directory by compacting it. This can take time and impact performance.

Snapshot and Restore

Create a snapshot of the database:

etcdctl snapshot save snapshot.db

Saves the current etcd database to snapshot.db.

Restore from a snapshot:

etcdctl snapshot restore snapshot.db --data-dir /path/to/new/data/dir

Restores the etcd database from snapshot.db into the specified data directory. Note: The etcd server must be stopped before restoring.

List snapshot contents:

etcdctl snapshot status snapshot.db

Shows metadata about the snapshot file.

Miscellaneous

Set a key with a specific revision:

etcdctl put mykey "myvalue" --rev=12345

Sets mykey to myvalue only if the current revision is exactly 12345.

Get a key at a specific revision:

etcdctl get mykey --rev=12345

Retrieves the value of mykey as it was at revision 12345.

Enable debugging output:

etcdctl --debug put mykey "myvalue"

Prints detailed debugging information for the command.

Common Patterns

Watch for a key and print its value on change:

etcdctl watch mykey --print-value

This will continuously print the value of mykey whenever it’s updated.

Atomically get and delete a key:

etcdctl txn --key=/my/key --compare val="expected_value" --then del /my/key

This ensures that you only delete the key if it has the expected value, preventing race conditions.

Implementing a simple leader election using leases:

  1. Candidate tries to put a key with a lease:
    LEADER_KEY="/my_app/leader"
TTL=5 # seconds
LEASE_ID=$(etcdctl lease grant $TTL -w value | cut -d: -f2 | tr -d ' ')
etcdctl put $LEADER_KEY "candidate-1" --lease=$LEASE_ID
  2. Other candidates watch the key: If a candidate sees the key exists, it knows there’s a leader.
  3. Leader keeps lease alive: The leader periodically calls etcdctl lease keep-alive $LEASE_ID.
  4. If leader fails: The lease expires, the key is deleted. The next candidate that successfully puts the key becomes the new leader.

Bulk put operations:

echo "key1,value1" > data.csv
echo "key2,value2" >> data.csv
awk -F, '{print "put", $1, $2}' data.csv | etcdctl --command-timeout=30s

This reads key-value pairs from a CSV and performs put operations.

Backup etcd cluster (snapshot):

ETCDCTL_ENDPOINTS="https://etcd-peer1:2379,https://etcd-peer2:2379" \
ETCDCTL_CACERT="/etc/etcd/ca.crt" \
ETCDCTL_CERT="/etc/etcd/server.crt" \
ETCDCTL_KEY="/etc/etcd/server.key" \
etcdctl snapshot save /backups/etcd-snapshot-$(date +%Y-%m-%d_%H-%M-%S).db

This command performs a snapshot backup of a TLS-enabled etcd cluster.

Gotchas

  • Endpoint Configuration: Forgetting to set ETCDCTL_ENDPOINTS or having it point to the wrong cluster is the most common initial problem.
  • TLS Configuration: If your etcd cluster uses TLS, you must configure ETCDCTL_CACERT, ETCDCTL_CERT, and ETCDCTL_KEY correctly. Mismatched certificates or incorrect paths will lead to connection errors.
  • etcdctl member list vs. etcdctl get: member list shows cluster nodes, not keys. To see keys, you need get commands.
  • Compaction and Defragmentation: compact only removes historical data. defrag physically rewrites the data file to reclaim disk space. Both are important for managing etcd’s disk usage.
  • Lease TTL: If a lease TTL is too short, a leader might be prematurely replaced. If it’s too long, a failed leader might hold the leadership for too long.
  • etcdctl snapshot restore requires a stopped server: You cannot restore a snapshot while the etcd server is running. The server must be shut down, the data directory cleared (or specified as new), and then the restore command executed before starting the server again with the restored data.
  • Key Naming: Keys are byte strings. Be mindful of how characters like / are used and how lexicographical ordering affects range queries.
  • No Implicit Directory Creation: etcd is a flat key-value store. When you put /a/b/c, you are creating the key /a/b/c. There are no implicit directories created. You can simulate directories by having keys like /a/b/c and /a/b/d.