docs/source/concepts/bucket-versioning.rst

Bucket Versioning

minio

Table of Contents

MinIO supports keeping multiple "versions" of an object in a single bucket. Write operations which would normally overwrite an existing object instead result in the creation of a new versioned object. MinIO versioning protects from unintended overwrites and deletions while providing support for "undoing" a write operation. Bucket versioning also supports retention and archive policies.

<Diagram>

MinIO generates a unique immutable ID for each object. If a PUT request contains an object name which duplicates an existing object, MinIO does not overwrite the "older" object. Instead, MinIO retains all object versions while considering the most recently written "version" of the object as "latest". Applications retrieve the latest object version by default, but may retrieve any other version in the history of that object. To view all versions of an object or objects in a bucket, use the mc ls versions command.

By default, deleting an object does not remove all existing versions of that object. Instead, MinIO places a "delete" marker for the object, such that applications requesting only the latest object versions do not see the object. Applications may retrieve earlier versions of that object. To completely delete an object and its entire version history, use the mc rm versions command.

Enable Bucket Versioning

Enabling bucket versioning on a MinIO deployment requires that the deployment have at least four disks. Specifically, Bucket Versioning depends on Erasure Coding <minio-erasure-coding>. For MinIO deployments that meet the disk requirements, use the mc version enable command to enable versioning on a specific bucket.

The mc version command may work on other S3-compatible services depending on their implementation of and support for the AWS S3 API.

Buckets with Existing Content

After enabling bucket versioning, MinIO begins generating version IDs for new objects created in the bucket. MinIO does not iterate through existing objects to generate version IDs. Existing unversioned objects in a versioned bucket have a null version ID.

Suspend Bucket Versioning

You can suspend bucket versioning at any time using mc version disable. MinIO retains all existing object versions. During suspension, MinIO allows overwrites of any unversioned object. Applications can continue referencing any existing object version.

You can later re-enable object versioning on the bucket. MinIO resumes generating version IDs for new objects, and does not retroactively generate version IDs for existing unversioned objects. MinIO lists unversioned objects with a null version ID.

Version ID Generation

MinIO version ID's are DCE 1.1/RFC 4122-compliant Universally Unique Identifiers (UUID) version 4. Each UUID is a random 128-bit number intended to have a high likelihood of uniqueness over space and time, and that are computationally difficult to guess. UUID's are globally unique that can be generated without contacting a global registration authority.

MinIO object version UUID's are immutable after creation.

Versioning Dependent Features

The following MinIO features require bucket versioning for functionality:

• Object Locking (mc lock and mc mb with-lock)
• Object Legal Hold (mc legalhold)
• Bucket Replication (mc admin bucket remote and mc replicate)