How to use the command etcd (with examples)

Etcd is a distributed, reliable key-value store designed for storing critical data in a distributed system. It provides a simple and consistent interface for managing and accessing data efficiently. This article will explore various use cases of the etcd command.

Use case 1: Start a single-node etcd cluster

Code:

etcd

Motivation: Starting a single-node etcd cluster is the basic setup for utilizing etcd’s key-value store in a distributed system. This command will start a single-node etcd instance, using default settings.

Explanation: The command “etcd” starts an etcd cluster with default configurations. By default, it listens for client requests on the local machine using port 2379.

Example output:

2022-01-01 12:34:56.789 [INFO] main: etcd version 3.6.0
2022-01-01 12:34:56.789 [INFO] main: Git SHA:  <git-sha>
...
2022-01-01 12:34:56.789 [INFO] etcdserver:  restoring snapshot ("meta-dir-path" -> "snapshot-path") from file
...
2022-01-01 12:34:56.789 [INFO] etcdserver:  recovered store from snapshot at index 42
2022-01-01 12:34:56.789 [INFO] etcdserver/membership: added member {"id": "xyz", "name": "etcd-member-1"} with
    version 3.6 to cluster
...
2022-01-01 12:34:56.789 [INFO] etcdserver/membership: added member {"id": "xyz", "name": "etcd-member-1"} with
    version 3.6 to cluster
2022-01-01 12:34:56.789 [INFO] etcdserver:  starting server... [version: 3.6.0, cluster version: to_be_decided]
2022-01-01 12:34:56.789 [INFO] embed: Type Ctrl-C twice within 2s to gracefully quit etcd
...

Use case 2: Start a single-node etcd cluster, listening for client requests on a custom URL

Code:

etcd --advertise-client-urls http://127.0.0.1:1234 --listen-client-urls http://127.0.0.1:1234

Motivation: In some cases, it may be necessary to listen for etcd client requests on a specific URL. This use case allows the operator to configure the etcd cluster to listen on a custom URL.

Explanation: The --advertise-client-urls flag specifies the URL(s) to advertise to clients. In this example, the custom URL http://127.0.0.1:1234 is used. The --listen-client-urls flag specifies the URL(s) to listen for client requests.

Example output:

2022-01-01 12:34:56.789 [INFO] main: etcd version 3.6.0
2022-01-01 12:34:56.789 [INFO] main: Git SHA:  <git-sha>
...
2022-01-01 12:34:56.789 [INFO] etcdserver/api: enabled capabilities for version 3.6
...
2022-01-01 12:34:56.789 [INFO] etcdserver/api: listening for client requests on http://127.0.0.1:1234
...

Use case 3: Start a single-node etcd cluster with a custom name

Code:

etcd --name my_etcd_cluster

Motivation: Naming the etcd cluster can help with identification and organization in a larger distributed system. This use case allows the operator to provide a custom name for the etcd cluster.

Explanation: The --name flag sets the name of the etcd cluster. In this example, the name is set to my_etcd_cluster.

Example output:

2022-01-01 12:34:56.789 [INFO] main: etcd version 3.6.0
2022-01-01 12:34:56.789 [INFO] main: Git SHA:  <git-sha>
...
2022-01-01 12:34:56.789 [INFO] etcdserver/api: serving insecure client requests on 127.0.0.1:2379, and serving
    insecure peer requests on localhost:2380; for more secure communication, use HTTPS or a VPN
2022-01-01 12:34:56.789 [INFO] etcdserver/membership: added member {"id": "xyz", "name": "my_etcd_cluster"} with
    version 3.6 to cluster
...
2022-01-01 12:34:56.789 [INFO] etcdserver: starting server... [version: 3.6.0, cluster version: to_be_decided]
2022-01-01 12:34:56.789 [INFO] embed: Type Ctrl-C twice within 2s to gracefully quit etcd
...

Use case 4: Start a single-node etcd cluster with extensive metrics available

Code:

etcd --enable-pprof --metrics extensive

Motivation: Enabling extensive metrics can provide valuable insights into the performance and health of the etcd cluster. This use case allows the operator to enable the pprof and extensive metrics.

Explanation: The --enable-pprof flag enables HTTP profiling on the etcd server, making pprof endpoints available at http://localhost:2379/debug/pprof/. The --metrics flag sets the level of metrics to be collected. In this example, the level is set to extensive.

Example output:

...
2022-01-01 12:34:56.789 [INFO] embed: serving pprof endpoints on http://localhost:2379/debug/pprof/
...
2022-01-01 12:34:56.789 [INFO] etcdserver: exports pprof metrics on http://localhost:2379/manifest
...

Conclusion:

The etcd command provides various options to customize the behavior and configuration of the etcd cluster. By exploring these examples, users can gain a better understanding of how to utilize the etcd key-value store effectively in their distributed systems.