Skip to content

Commit de17a03

Browse files
committed
Add clarification on the usage of etcdutl vs etcdctl
1 parent c5cb074 commit de17a03

File tree

1 file changed

+57
-10
lines changed

1 file changed

+57
-10
lines changed

content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md

Lines changed: 57 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,16 @@ guide on a cluster with at least two nodes that are not acting as control plane
2020
nodes. If you do not already have a cluster, you can create one by using
2121
[minikube](https://minikube.sigs.k8s.io/docs/tutorials/multi_node/).
2222

23+
### Understanding etcdctl and etcdutl
24+
25+
`etcdctl` and `etcdutl` are command-line tools used to interact with etcd clusters, but they serve different purposes:
26+
27+
- `etcdctl`: This is the primary command-line client for interacting with etcd over a network. It is used for day-to-day operations such as managing keys and values, administering the cluster, checking health, and more.
28+
29+
- `etcdutl`: This is an administration utility designed to operate directly on etcd data files, including migrating data between etcd versions, defragmenting the database, restoring snapshots, and validating data consistency. For network operations, `etcdctl` should be used.
30+
31+
For more information on `etcdutl`, you can refer to the [etcd recovery documentation](https://etcd.io/docs/v3.5/op-guide/recovery/).
32+
2333
<!-- steps -->
2434

2535
## Prerequisites
@@ -281,17 +291,54 @@ ETCDCTL_API=3 etcdctl --endpoints $ENDPOINT snapshot save snapshot.db
281291

282292
Verify the snapshot:
283293

284-
```shell
285-
ETCDCTL_API=3 etcdctl --write-out=table snapshot status snapshot.db
286-
```
294+
{{< tabs name="etcd_verify_snapshot" >}}
295+
{{% tab name="Use etcdutl" %}}
296+
The below example depicts the usage of the `etcdutl` tool for verifying a snapshot:
287297

288-
```console
289-
+----------+----------+------------+------------+
290-
| HASH | REVISION | TOTAL KEYS | TOTAL SIZE |
291-
+----------+----------+------------+------------+
292-
| fe01cf57 | 10 | 7 | 2.1 MB |
293-
+----------+----------+------------+------------+
294-
```
298+
```shell
299+
etcdutl --write-out=table snapshot status snapshot.db
300+
```
301+
302+
This should generate an output resembling the example provided below:
303+
304+
```console
305+
+----------+----------+------------+------------+
306+
| HASH | REVISION | TOTAL KEYS | TOTAL SIZE |
307+
+----------+----------+------------+------------+
308+
| fe01cf57 | 10 | 7 | 2.1 MB |
309+
+----------+----------+------------+------------+
310+
```
311+
312+
{{% /tab %}}
313+
{{% tab name="Use etcdctl (Deprecated)" %}}
314+
315+
{{< note >}}
316+
The usage of `etcdctl snapshot status` has been **deprecated** since etcd v3.5.x and is slated for removal from etcd v3.6.
317+
It is recommended to utilize [`etcdutl`](https://github.com/etcd-io/etcd/blob/main/etcdutl/README.md) instead.
318+
{{< /note >}}
319+
320+
The below example depicts the usage of the `etcdctl` tool for verifying a snapshot:
321+
322+
```shell
323+
export ETCDCTL_API=3
324+
etcdctl --write-out=table snapshot status snapshot.db
325+
```
326+
327+
This should generate an output resembling the example provided below:
328+
329+
```console
330+
Deprecated: Use `etcdutl snapshot status` instead.
331+
332+
+----------+----------+------------+------------+
333+
| HASH | REVISION | TOTAL KEYS | TOTAL SIZE |
334+
+----------+----------+------------+------------+
335+
| fe01cf57 | 10 | 7 | 2.1 MB |
336+
+----------+----------+------------+------------+
337+
```
338+
339+
340+
{{% /tab %}}
341+
{{< /tabs >}}
295342

296343
### Volume snapshot
297344

0 commit comments

Comments
 (0)