# Turn on versioning

Keep the earlier version of an object on every overwrite and delete, so a mistake can be undone.

With versioning on, an overwrite or a delete keeps the earlier version, which you can read or
restore by its version id (see [Restore an earlier version](restore-an-object-version.md)). Every
version is stored and billed like an object. Replace _example-uploads_ with your bucket's name.

**Important:**
Once on, versioning can only be paused (S3 calls it _Suspended_), never removed.

## Prerequisites

- Permission for `s3:PutBucketVersioning` on the bucket, and `s3:PutLifecycleConfiguration` to add
  the rule that deletes old versions in the same step.
- In the console, also `s3:GetBucket` on the bucket to open it (without it the bucket's page says
  "Access denied").
- For a bucket on a storage cluster that was created without object lock: the bucket is still
  empty (see [Storage locations](storage-locations.md#own-storage)). Turn versioning on right after
  creating the bucket.

## Turn versioning on

**Console**
1. Open the bucket, then choose **Versioning & lifecycle**.
2. Under **Versioning**, choose **Turn on versioning**. The sheet **Turn on versioning for
   example-uploads** opens.
3. (Optional) Select **Delete old versions after _N_ days** and enter the number of days (`30` is
   filled in). This adds a lifecycle rule named `expire-old-versions`. Unselected, old versions are
   kept and billed until you delete them.
4. Choose **Turn on versioning**.

The status shows **On**.

**CLI**
```sh
dcloud s3 bucket-versioning set example-uploads --enabled
```

**API**
```http
PUT /s3/api/buckets/example-uploads/versioning
{ "enabled": true }
```

**Terraform**
```hcl
resource "dcloud_bucket_versioning" "uploads" {
  bucket  = dcloud_bucket.uploads.id
  enabled = true
}
```

Destroying the resource pauses versioning.

Over S3, `aws s3api put-bucket-versioning` does the same.

## Pause versioning

In the console, choose **Pause versioning**, then **Pause versioning** in the dialog; when another
bucket replicates into this one, the dialog first asks you to enter the bucket's name. While this
bucket replicates to another, or has object lock, **Pause versioning** is unavailable. With the CLI,
`dcloud s3 bucket-versioning set example-uploads --no-enabled`; with the API,
`{ "enabled": false }`. While paused, an overwrite replaces the object and a delete removes it for
good; versions kept so far stay, and are billed. **Resume versioning** turns it on again at once.

## If it is refused

- 409 `Versioning cannot be suspended on an object-lock bucket`: object lock keeps versioning on
  for good.
- 409 `example-uploads replicates to another bucket, which needs versioning. Remove the replication first.`
- 409 `example-uploads shares a storage pool with other buckets, so versioning, lifecycle rules and other store settings need a bucket of its own: that move happens on its own while the bucket is empty, and example-uploads has objects. Set it on an empty bucket, or copy the objects into a new bucket and set it there first.`
- 404 `Not found` for a bucket the platform manages (a database's backups).

## Related

- [Restore an earlier version](restore-an-object-version.md)
- [Set lifecycle rules](set-lifecycle-rules.md)
- `s3.bucket-versioning.set` · `dcloud s3 bucket-versioning set` · `dcloud_bucket_versioning`
