Welcome to the upcoming version of the MinIO Documentation! The content on this page is under active development and may change at any time. If you can't find what you're looking for, check our legacy documentation. Thank you for your patience.

Bucket Versioning

Overview

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 is a prerequisite for configuring object locking and retention rules.

For versioned buckets, any write operation that mutates an object results in a new version of that object with a unique version ID. MinIO marks the “latest” version of the object that clients retrieve by default. Clients can then explicitly choose to list, retrieve, or remove a specific object version.

Deleting an object results in a special DeleteMarker tombstone that marks an object as deleted while retaining all previous versions of that object.

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 disk 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:

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.

Object with Multiple Versions

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. Clients performing GET operations on that object do not return any results, as MinIO does not return the DeleteMarker back as part of the response. Similarly, performing a LIST operation by default returns only objects which are not a DeleteMarker.

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.

The following mc commands operate on DeleteMarkers or versioned objects:

Tutorials

Enable Bucket Versioning

Note

Versioning requires erasure coding and is only available on distributed MinIO deployments.

You can enable versioning using the MinIO Console, the MinIO mc CLI, or using an S3-compatible SDK. Versioning is a bucket-scoped feature. You cannot enable versioning on only a prefix or subset of objects in a bucket.

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

MinIO Console Bucket Management

From the Bucket view, click the Versioning field to enable versioning on the bucket.

MinIO Console Bucket minio-lifecycle-management

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

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

mc version enable 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.

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.

Select the Buckets section of the MinIO Console to access bucket creation and management functions.

Select the bucket row from the list of buckets. You can use the Search bar to filter the list.

MinIO Console Bucket Management

From the Bucket view, click the Versioning field to disable versioning on the bucket.

MinIO Console Bucket minio-lifecycle-management

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

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

mc version disable 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 results 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.