# Back up a cluster

See the etcd snapshots {{product}} takes of a cluster, and take one now.

Replace _my-cluster_ with your cluster's name or id.

Deutsche Cloud backs up every cluster's etcd, the database that holds every Kubernetes object, at no
charge. **Volumes and their data are not part of it**: a restore brings back objects (Deployments,
Services, Secrets, PersistentVolumeClaims), not what is written on volumes.

| Snapshot      | When                                                          | Kept                                      |
| ------------- | ------------------------------------------------------------- | ----------------------------------------- |
| `hourly`      | every hour, while the cluster is `active` or `updating`       | 7 days; the first of each UTC day 30 days |
| `on-demand`   | when you ask, at most one per 10 minutes                      | 30 days, the 10 newest                    |
| `pre-upgrade` | before a control-plane upgrade replaces its first machine     | 30 days                                   |
| `pre-restore` | before a restore                                              | 30 days                                   |
| `final`       | when the cluster is deleted, unless it is deleted permanently | 7 days                                    |

Snapshots are only taken on a control plane built with backups (see `not-enabled` below); on one
built before, there are no `pre-upgrade`, `pre-restore` or `final` snapshots either. A deletion
waits at most 5 minutes for its `final` snapshot, then goes on without it.

While the cluster exists, its newest verified snapshot is never deleted, however old; a deleted
cluster keeps only its `final` snapshot. Each snapshot is taken on a control-plane machine, checked
by restoring it into a scratch directory there (`verifiedAt`), and sealed under Deutsche Cloud's master
key in its object storage. Snapshots cannot be downloaded.

## Prerequisites

- Permission for `eks:ListClusterSnapshots` to see snapshots, and `eks:CreateClusterSnapshot` to
  take one.
- In the console, also `eks:DescribeCluster` to open the cluster.
- To take one: the cluster is `active` or `updating`, and its control plane was built with backups.

## Take a snapshot now

**Console**
1. Open **Kubernetes**, open the cluster, then choose **Backups**.
2. Under **Snapshots**, choose **Take a snapshot now**. The button is not there when the backup
   status is not enabled.

The snapshot is listed as being taken, then as verified (or failed).

**CLI**
```sh
dcloud eks snapshots create my-cluster
dcloud eks snapshots list my-cluster
```

**API**
```http
POST /eks/api/clusters/my-cluster/snapshots
```

## Result

The answer is `202` with the snapshot, kind `on-demand`, status `pending`, and `evicts`: the
on-demand snapshot it pushes out of the 10 kept, or `null`. It is `pending` until it has been taken,
checked and uploaded, then `available`. A snapshot that has not arrived after 15 minutes is
`failed` with the error "no snapshot arrived within 15 minutes (no leading control-plane machine
took it)", and **Activity** records it; failed snapshots are kept a day.

## Backup status

`backup.status` on the cluster and in `snapshots list`:

| Status          | Meaning                                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| `ok`            | A verified snapshot within the last 2 hours.                                                              |
| `first-pending` | No verified snapshot yet, and the cluster was created less than 2 hours ago.                              |
| `stale`         | No verified snapshot for over 2 hours; Deutsche Cloud's operators are alerted.                               |
| `not-enabled`   | The control plane was built before etcd backups; upgrading it (which replaces its machines) enables them. |

## Refusals

- `409` "A snapshot is being taken; wait for it to finish".
- `409` "One on-demand snapshot per 10 minutes; the next in … min".
- `409` "The cluster is _creating_; snapshots are taken of a running control plane".
- `409` "This control plane was built before etcd backups; replace it (upgrade) to enable them".

## Related

- [Restore a cluster from a snapshot](restore-a-cluster.md)
- `eks.snapshots.create` · `dcloud eks snapshots create`
