> For the complete documentation index, see [llms.txt](https://docs.weka.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.weka.io/additional-protocols/s3/s3-versioning.md).

# S3 versioning

Protect S3 objects from accidental overwrites and deletions. Bucket versioning retains previous versions and creates delete markers for recovery.

## Key terms

* **Current version:** The most recent version of an object. It's what you retrieve by default.
* **Non-current version:** Any earlier version of an object, retained after an update or overwrite.
* **Delete marker:** A placeholder that becomes the current version when you delete an object. It has its own version ID but no data, and it hides the object from standard list and GET requests. Earlier versions remain retrievable by version ID.
* **Version ID:** A unique identifier for each object version. Objects stored before you enable versioning have a version ID of `null`.

## Versioning states

Manage bucket versioning through these state transitions:

`Unset` is the initial bucket state. After enabling or suspending versioning, you cannot return to `Unset`.

* `Unset` → `Enabled`
* `Unset` → `Suspended`
* `Enabled` ↔ `Suspended`

## How enabled versioning affects operations

These behaviors apply when bucket versioning is `Enabled`.

* **Update or overwrite:** Creates a new version. WEKA retains the previous version.
* **Delete:** Creates a delete marker instead of removing the object. The object appears deleted, but every version remains accessible by version ID.
* **Delete a delete marker:** Restores the most recent non-current version as current.
* **Delete a specific version ID:** Permanently removes that version.
* **List a bucket:** Returns only current versions. List object versions to see all versions and delete markers.

## Versioning behavior across file protocols

Identify how object operations behave when you access a versioned bucket through a file protocol instead of S3. File-protocol access refers to POSIX, NFS, and SMB access, and behavior is identical across all three.

* **Delete through S3:** WEKA creates a delete marker and sets it as the current version. A standard `GET` returns 404, and the object isn't accessible through a file protocol. Every previous version remains retrievable by version ID or through a list object versions request.
* **Delete through a file protocol:** WEKA removes the object without creating a delete marker. A standard S3 `GET` returns 404, and the object isn't accessible through a file protocol. Previous versions remain retrievable by version ID or through a list object versions request.
* **Rename or move through a file protocol:** WEKA treats the operation as a file-protocol delete of the original path. The object at the original path is no longer the current version, and WEKA doesn't create a delete marker. The moved file remains accessible through the file protocol at its new path. Previous versions remain retrievable by version ID or through a list object versions request.
* **Copy through a file protocol:** The source object is unchanged and remains the current version, with versioning intact. The copy is a new, independent object at the destination path.

#### Behavior summary

<table><thead><tr><th width="173">Operation</th><th width="146">Delete marker created</th><th>Standard S3 GET</th><th width="128">Versions by version ID</th><th>File-protocol access</th></tr></thead><tbody><tr><td>Delete via S3</td><td>Yes</td><td>404</td><td>Retained</td><td>Not accessible</td></tr><tr><td>Delete via file protocol</td><td>No</td><td>404</td><td>Retained</td><td>Not accessible</td></tr><tr><td>Rename or move via file protocol</td><td>No</td><td>404 at original path</td><td>Retained</td><td>Accessible at new path</td></tr><tr><td>Copy via file protocol</td><td>No</td><td>Source unchanged</td><td>Retained</td><td>Source and copy accessible</td></tr></tbody></table>

To keep version state consistent, manage versioned buckets through the S3 protocol.

## Manage bucket versioning using the CLI

Check, enable, or suspend versioning for an S3 bucket.

**Before you begin**

* Ensure the WEKA CLI is configured and you can manage the target bucket.
* Enable versioning for the cluster. Versioning is off by default, and the bucket commands fail with `MethodNotAllowed: The feature is disabled in the global configuration` until you enable it.

  ```bash
  weka s3 cluster update --allow-versioning
  ```

{% hint style="warning" %}
You cannot disable cluster versioning after you enable it. To stop retaining new versions, suspend versioning on the individual buckets.
{% endhint %}

**CLI commands:**

* Check the versioning state.

  ```bash
  weka s3 bucket versioning get <bucket-name>
  ```
* Enable versioning.

  ```bash
  weka s3 bucket versioning enable <bucket-name>
  ```
* Suspend versioning.

  ```bash
  weka s3 bucket versioning suspend <bucket-name>
  ```

For versioning API support, see [S3 supported APIs and limitations](/additional-protocols/s3/s3-limitations.md#supported-s3-apis).

## Suspending versioning

When you suspend versioning on a bucket:

* New objects receive a version ID of `null` and overwrite only an existing `null` version. Earlier numbered versions remain retained.
* Deleting an object with a `null` version ID removes it and inserts a delete marker with a `null` version ID.
* Deleting a specific version ID still permanently removes that version.

## Reclaim capacity from noncurrent versions

A versioned bucket retains every earlier version of an object, and those versions consume capacity until you expire them. Suspending versioning does not remove the versions already retained.

Add a lifecycle rule with the `--noncurrent` option to expire earlier versions while keeping the current version of each object:

```bash
weka s3 bucket lifecycle-rule add <bucket-name> <expiry-days> --noncurrent
```

The cluster raises `S3VersioningNoNoncurrentExpirationRule` on a versioned bucket that has no such rule, and `S3VersioningNoDataservIlm` when no active Data Services container has lifecycle management configured.

**Related topics**

[S3 lifecycle rules management](/additional-protocols/s3/s3-information-lifecycle-management.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.weka.io/additional-protocols/s3/s3-versioning.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.