diff --git a/content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md b/content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md index 93402dd5d3..7c4fa3f741 100644 --- a/content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md +++ b/content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md @@ -20,6 +20,21 @@ guide on a cluster with at least two nodes that are not acting as control plane nodes. If you do not already have a cluster, you can create one by using [minikube](https://minikube.sigs.k8s.io/docs/tutorials/multi_node/). +### Understanding etcdctl and etcdutl + +`etcdctl` and `etcdutl` are command-line tools used to interact with etcd clusters, but they serve different purposes: + +- `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. + +- `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. + +For more information on `etcdutl`, you can refer to the [etcd recovery documentation](https://etcd.io/docs/v3.5/op-guide/recovery/). + ## Prerequisites @@ -281,17 +296,54 @@ ETCDCTL_API=3 etcdctl --endpoints $ENDPOINT snapshot save snapshot.db Verify the snapshot: -```shell -ETCDCTL_API=3 etcdctl --write-out=table snapshot status snapshot.db -``` +{{< tabs name="etcd_verify_snapshot" >}} +{{% tab name="Use etcdutl" %}} + The below example depicts the usage of the `etcdutl` tool for verifying a snapshot: -```console -+----------+----------+------------+------------+ -| HASH | REVISION | TOTAL KEYS | TOTAL SIZE | -+----------+----------+------------+------------+ -| fe01cf57 | 10 | 7 | 2.1 MB | -+----------+----------+------------+------------+ -``` + ```shell + etcdutl --write-out=table snapshot status snapshot.db + ``` + + This should generate an output resembling the example provided below: + + ```console + +----------+----------+------------+------------+ + | HASH | REVISION | TOTAL KEYS | TOTAL SIZE | + +----------+----------+------------+------------+ + | fe01cf57 | 10 | 7 | 2.1 MB | + +----------+----------+------------+------------+ + ``` + +{{% /tab %}} +{{% tab name="Use etcdctl (Deprecated)" %}} + + {{< note >}} + The usage of `etcdctl snapshot status` has been **deprecated** since etcd v3.5.x and is slated for removal from etcd v3.6. + It is recommended to utilize [`etcdutl`](https://github.com/etcd-io/etcd/blob/main/etcdutl/README.md) instead. + {{< /note >}} + + The below example depicts the usage of the `etcdctl` tool for verifying a snapshot: + + ```shell + export ETCDCTL_API=3 + etcdctl --write-out=table snapshot status snapshot.db + ``` + + This should generate an output resembling the example provided below: + + ```console + Deprecated: Use `etcdutl snapshot status` instead. + + +----------+----------+------------+------------+ + | HASH | REVISION | TOTAL KEYS | TOTAL SIZE | + +----------+----------+------------+------------+ + | fe01cf57 | 10 | 7 | 2.1 MB | + +----------+----------+------------+------------+ + ``` + + +{{% /tab %}} +{{< /tabs >}} ### Volume snapshot