Bucket Versioning

Read Operations on Versioned Objects

Review each of the four images in this series to see how MinIO retrieves objects in a versioned bucket. Use the arrows on either side of the images to navigate from one to the next.

Object with Single Version

MinIO adds a unique version ID to each object as part of write operations.

Object with Multiple Versions

MinIO retains all versions of an object and marks the most recent version as the “latest”.

Retrieving the Latest Object Version

A read operation request without a version ID returns the latest version of the object.

Retrieving a Specific Object Version

Include the version ID to retrieve a specific version of an object during a read operation.

MinIO implicitly determines prefixes from object paths. Explicit prefix creation typically only occurs with Spark and similar workloads which apply legacy POSIX/HDFS directory creation behavior within the S3 context.

Versioning is Per-Namespace

MinIO uses the full namespace (the bucket and path to an object) for each object as part of determining object uniqueness. For example, all of the following namespaces are “unique” objects, where mutations of each object result in the creation of new object versions at that namespace:

databucket/object.blob
databucket/blobs/object.blob
blobbucket/object.blob
blobbucket/blobs/object.blob

While object.blob might be the same binary across all namespaces, MinIO only enforces versioning with a specific namespace and therefore considers each object.blob above as distinct and unique.

Versioning and Storage Capacity

MinIO does not perform incremental or differential-type versioning. For mutation-heavy workloads, this may result in substantial drive usage by older or aged object versions.

For example, consider a 1GB object containing log data. An application appends 100MB of data to the log and uploads to MinIO. MinIO would then contain both the 1GB and 1.1GB versions of the object. If the application repeated this process every day for 10 days, the bucket would eventually contain more than 14GB of data associated to a single object.

MinIO supports configuring configuring object lifecycle management rules to automatically expire or transition aged object versions and free up storage capacity. For example, you can configure a rule to automatically expire object versions 90 days after they become non-current (i.e. no longer the “latest” version of that object). See MinIO Object Expiration for more information.

You can alternatively perform manual removal of object versions using the following commands:

• mc rm --versions - Removes all versions of an object.

• mc rm --versions --older-than -

  Removes all versions of an object older than the specified calendar date.

Version ID Generation

MinIO generates a unique and immutable identifier for each versioned object as part of write operations. Each object version ID consists of a 128-bit fixed-size UUIDv4. UUID generation is sufficiently random to ensure high likelihood of uniqueness for any environment, are computationally difficult to guess, and do not require centralized registration process and authority to guarantee uniqueness.

MinIO does not support client-managed version ID allocation. All version ID generation is handled by the MinIO server process.

For objects created while versioning is disabled or suspended, MinIO uses a null version ID. You can access or remove these objects by specifying null as the version ID as part of S3 operations.

Versioned Delete Operations

Performing a DELETE operation on a versioned object creates a 0-byte DeleteMarker as the latest version of that object. For objects where the latest version is a DeleteMarker, clients must specify versioning flags or identifiers to perform GET/HEAD/LIST/DELETE operations on a prior version of that object. The default server behavior omits DeleteMarker objects from consideration for unversioned operations.

MinIO can utilize Lifecycle Management expiration rules to automatically remove versioned objects permanently. Otherwise, use manual DELETE operations to permanently remove non-current versioned objects or DeleteMarker objects.

To permanently delete an object version, perform the DELETE operation and specify the version ID of the object to delete. Versioned delete operations are irreversible.

Deleting an Object

Performing a DELETE operation on a versioned object produces a DeleteMarker for that object.

Reading a Deleted Object

Clients by default retrieve the “latest” object version. MinIO returns a 404-like response if the latest version is a DeleteMarker.

Retrieve Previous Version of Deleted Object

Clients can retrieve any previous version of the object by specifying the version ID, even if the “Latest” version is a DeleteMarker.

Delete a Specific Object Version

Clients can delete a specific object version by specifying the version ID as part of the DELETE operation. Deleting a specific version is permanent and does not result in the creation of a DeleteMarker.

The following mc commands operate on DeleteMarkers or versioned objects:

• Use mc ls --versions to view all versions of an object, including delete markers.

• Use mc cp --version-id=UUID ... to retrieve the version of the “deleted” object with matching UUID.

• Use mc rm --version-id=UUID ... to delete the version of the object with matching UUID.

• Use mc rm --versions to delete all versions of an object.

Enable Bucket Versioning

You can enable versioning using the MinIO Console, the MinIO mc CLI, or using an S3-compatible SDK.

MinIO Console

Select the Buckets section of the MinIO Console to access bucket creation and management functions. You can use the Search bar to filter the list.

Each bucket row has a Manage button that opens the management view for that bucket.

Toggle the Versioning field to enable versioning on the bucket.

The MinIO Console also supports enabling versioning as part of bucket creation. See Buckets for more information on bucket management using the MinIO Console.

MinIO CLI

Use the mc version enable command to enable versioning on an existing bucket:

mc version ALIAS/BUCKET

• Replace ALIAS with the alias of a configured MinIO deployment.

• Replace BUCKET with the target bucket on which to enable versioning.

Objects created prior to enabling versioning have a null version ID.

Exclude a Prefix From Versioning

You can exclude certain prefixes from versioning using the MinIO Client. This is useful for Spark/Hadoop workloads or others that initially create objects with temporary prefixes.

• Use mc version enable with the --excluded-prefixes option:

  mc version enable --excluded-prefixes "prefix1, prefix2" ALIAS/BUCKET
  

  • Replace ALIAS with the alias of a configured MinIO deployment.

  • Replace BUCKET with the name of the bucket you want to exclude prefixes for.

The list of --excluded-prefixes prefixes match all objects containing the specified strings in their prefix or name, similar to a regular expression of the form prefix*. To match objects by prefix only, use prefix/*.

For example, the following command excludes any objects containing _test or _temp in their prefix or name from versioning:

mc version enable --excluded-prefixes "_test, _temp" local/my-bucket

You can exclude up to 10 prefixes for each bucket. To add or remove prefixes, repeat the mc version enable command with an updated list. The new list of prefixes replaces the previous one.

To view the currently excluded prefixes, use mc version info with the --json option:

mc version info ALIAS/BUCKET --json

The command output resembles the following, with the list of excluded prefixes in the ExcludedPrefixes property:

$ mc version info local/my-bucket --json
{
 "Op": "info",
 "status": "success",
 "url": "local/my-bucket",
 "versioning": {
  "status": "Enabled",
  "MFADelete": "",
  "ExcludedPrefixes": [
   "prefix1, prefix2"
  ]
 }
}

To disable prefix exclusion and resume versioning all prefixes, repeat the mc version enable command without --excluded-prefixes:

mc version enable ALIAS/BUCKET

Exclude Folders from Versioning

You can exclude folders from versioning using the MinIO Client.

• Use mc version enable with the --exclude-folders option to exclude objects with names ending in / from versioning:

  mc version enable --exclude-folders ALIAS/BUCKET
  

  • Replace ALIAS with the alias of a configured MinIO deployment.

  • Replace BUCKET with the bucket you want to exclude folders for.

To check whether folders are versioned for a bucket, use the mc version enable command with the --json option. If the ExcludeFolders property is true, folders in that bucket are not versioned.

mc version enable --excluded-prefixes ALIAS/BUCKET --json

The command output resembles the following:

$ mc version info local/my-bucket --json
{
 "Op": "info",
 "status": "success",
 "url": "local/my-bucket",
 "versioning": {
  "status": "Enabled",
  "MFADelete": "",
  "ExcludeFolders": true
 }
}

To disable folder exclusion and resume versioning all folders, repeat the mc version enable command without --exclude-folders:

mc version enable ALIAS/BUCKET

Suspend Bucket Versioning

You can suspend bucket versioning at any time using the MinIO Console, the MinIO mc CLI, or using an S3-compatible SDK.

MinIO Console

Select the Buckets section of the MinIO Console to access bucket creation and management functions. You can use the Search bar to filter the list.

Each bucket row has a Manage button that opens the management view for that bucket.

Select the Versioning field and follow the instructions to suspend versioning in the bucket.

See Buckets for more information on bucket management using the MinIO Console.

MinIO CLI

Use the mc version suspend command to enable versioning on an existing bucket:

mc version suspend ALIAS/BUCKET

• Replace ALIAS with the alias of a configured MinIO deployment.

• Replace BUCKET with the target bucket on which to disable versioning.

Objects created while versioning is suspended are assigned a null version ID. Any mutations to an object while versioning is suspended result in overwriting that null versioned object. MinIO does not remove or otherwise alter existing versioned objects as part of suspending versioning. Clients can continue interacting with any existing object versions in the bucket.