Home • Explore • Blog • CI
☰



kubernetes
6th chunk of `content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md`
584ca7cae972e4426386ed30a14d614470ec9ec1f534ddfb0000000100000a0c
[etcd reconfiguration documentation](https://etcd.io/docs/current/op-guide/runtime-configuration/#remove-a-member)
for information on how to add members into an existing cluster.

## Restoring an etcd cluster

{{< caution >}}
If any API servers are running in your cluster, you should not attempt to
restore instances of etcd. Instead, follow these steps to restore etcd:

- stop *all* API server instances
- restore state in all etcd instances
- restart all API server instances

The Kubernetes project also recommends restarting Kubernetes components (`kube-scheduler`,
`kube-controller-manager`, `kubelet`) to ensure that they don't rely on some
stale data. In practice the restore takes a bit of time.  During the
restoration, critical components will lose leader lock and restart themselves.
{{< /caution >}}

etcd supports restoring from snapshots that are taken from an etcd process of
the [major.minor](https://semver.org/) version. Restoring a version from a
different patch version of etcd is also supported. A restore operation is
employed to recover the data of a failed cluster.

Before starting the restore operation, a snapshot file must be present. It can
either be a snapshot file from a previous backup operation, or from a remaining
[data directory](https://etcd.io/docs/current/op-guide/configuration/#--data-dir).

{{< tabs name="etcd_restore" >}}
{{% tab name="Use etcdutl" %}}
   When restoring the cluster using [`etcdutl`](https://github.com/etcd-io/etcd/blob/main/etcdutl/README.md),
   use the `--data-dir` option to specify to which folder the cluster should be restored:

   ```shell
   etcdutl --data-dir <data-dir-location> snapshot restore snapshot.db
   ```
   where `<data-dir-location>` is a directory that will be created during the restore process.

{{% /tab %}}
{{% tab name="Use etcdctl (Deprecated)" %}}

   {{< note >}}
   The usage of `etcdctl` for restoring 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 the restore operation:

   ```shell
   export ETCDCTL_API=3
   etcdctl --data-dir <data-dir-location> snapshot restore snapshot.db
   ```

   If `<data-dir-location>` is the same folder as before, delete it and stop the etcd process before restoring the cluster. 
   Otherwise, change etcd configuration and restart the etcd process after restoration to have it use the new data directory:
Title: Restoring an etcd Cluster from a Snapshot
Summary
This section details the process of restoring an etcd cluster from a snapshot, emphasizing the importance of stopping all API servers before the restoration and restarting them afterwards. It also recommends restarting other Kubernetes components. etcd supports restoring from snapshots of the same major.minor version or different patch versions. The restoration process involves using either `etcdutl` or the deprecated `etcdctl` tool, with a preference for `etcdutl`. The `--data-dir` option is used to specify the restoration directory. If restoring to the same data directory, the old directory must be deleted, and the etcd process stopped. Otherwise the etcd configuration should be updated to use the new data directory.