etcdctl

Display the value associated with a specified key

$ etcdctl get [my/key]

$ etcdctl put [my/key] [my_value]

$ etcdctl del [my/key]

$ etcdctl put [my/file] < [path/to/file.txt]

$ etcdctl snapshot save [path/to/snapshot.db]

$ etcdctl snapshot restore [path/to/snapshot.db]

$ etcdctl user add [my_user]

$ etcdctl watch [my/key]

etcdctl [global-flags] command [subcommand] [command-flags] [arguments]

Common commands:
    get key [options]
    put key value [options]
    del key [options]
    member subcommand [options]
    watch key [options]
    lease subcommand [options]

--endpoints=urls
    Comma-separated list of etcd endpoints (e.g., '127.0.0.1:2379').

--user=username
    Username for etcd authentication.

--password=password
    Password for etcd authentication. Can also be set via ETCDCTL_PASSWORD environment variable.

--password-file=path
    Path to file containing password for etcd authentication.

--cert=path
    Path to client certificate file for TLS authentication.

--key=path
    Path to client key file for TLS authentication.

--cacert=path
    Path to CA certificate file for etcd server verification.

--dial-timeout=duration
    Dial timeout for client connections (e.g., '5s').

--command-timeout=duration
    Timeout for the entire command (e.g., '10s').

--debug
    Enable client-side debugging information.

--cluster
    Deprecated for v3 API, use --endpoints instead for specifying cluster members.

etcdctl is the command-line client for etcd, a strongly consistent, distributed key-value store that provides a reliable way to store data that needs to be accessed by a distributed system or a cluster of machines. It is notably used by applications like Kubernetes to store cluster state and configuration.

The etcdctl utility allows users to interact with an etcd cluster from the command line, performing a wide range of operations. These operations include basic key-value manipulations (get, put, delete, watch), managing etcd cluster members (member add, remove, list), handling leases for ephemeral keys, managing user authentication and roles, and performing maintenance tasks like defragmentation and snapshotting.

It primarily supports the etcd API v3, which is the recommended and actively developed API version for modern deployments. etcdctl is an essential tool for administrators and developers working with etcd-powered distributed systems, providing a direct interface to manage and troubleshoot the cluster's state.

Working with etcdctl requires careful consideration, especially in production environments.

1. Network Connectivity and Latency: etcdctl depends on stable network connectivity to the etcd cluster. High latency or packet loss can lead to command timeouts or inconsistent state views.
2. Security: Always use TLS (SSL/certificates) for secure communication between etcdctl and the etcd cluster, and consider enabling authentication and authorization to prevent unauthorized access.
3. API Version Compatibility: Be aware that etcdctl primarily targets the v3 API. Using commands specific to v2 or targeting a v2 cluster without proper API version specification can lead to errors.
4. Idempotency: Not all etcdctl commands are idempotent. Running the same command multiple times might have different effects, especially for operations like 'member add'.
5. Cluster State Awareness: When performing critical operations like 'member remove' or database defragmentation, ensure you understand the current state of the etcd cluster and its impact on dependent services (e.g., Kubernetes).

etcdctl primarily operates against the etcd v3 API, which is the recommended and actively developed version. While some legacy commands for the v2 API exist (e.g., etcdctl --api-version=2), new development and best practices strongly encourage using v3. The v3 API offers improved performance, stronger consistency guarantees, and a richer set of features, including leases, watch streaming, and multi-version concurrency control (MVCC).

Many etcdctl global flags can also be set via environment variables, prefixing the flag name with ETCDCTL_ and converting hyphens to underscores (e.g., ETCDCTL_ENDPOINTS for --endpoints, ETCDCTL_USER for --user). This is often useful for scripting or persistent configuration.

etcd was originally developed by CoreOS (later acquired by Red Hat) as a crucial component for distributed systems, particularly for their container orchestration platform, Kubernetes. etcdctl emerged as the primary command-line interface to interact with this key-value store. Its development has closely tracked the evolution of the etcd project itself, including the transition from API v2 to API v3, which brought significant improvements in performance, scalability, and consistency. As etcd became an industry standard for distributed consensus and state management, especially with its adoption as the backbone for Kubernetes, etcdctl cemented its role as an indispensable tool for cluster operators and developers. Its continuous development focuses on robustness, security, and usability for managing highly available, distributed applications.

etcd(1), curl(1), systemctl(1)