Using Object Versioning

Object versioning provides data protection against accidental or malicious object update, overwrite, or deletion.

Important

Standard Oracle Cloud Infrastructure pricing applies to each bucket that is enabled for versioning. You are charged for all objects and object versions (including deleted object versions) stored in the bucket. Object versions are retained until you explicitly delete them.

Object versioning does increase your storage costs.

This topic describes Object Storage versioning and provides details on how to create and manage object versions.

About Object Versioning

Object versioning is enabled at the bucket level. Versioning directs Object Storage to automatically create an object version each time a new object is uploaded, an existing object is overwritten, or when an object is deleted. You can enable object versioning at bucket creation time or later.

A bucket that is versioning-enabled can have many versions of an object. There is always one latest version of the object and zero or more previous versions.

The remainder of this document refers to the latest version as the object and all previous versions collectively as object versions.

Understanding Object Versioning Status

Each Object Storage bucket has object versioning status of disabled, enabled, or suspended. By default, object versioning is disabled on a bucket. It's important to understand the behavior associated with each object versioning status.

Disabled

If object versioning is disabled on a bucket:

  • Object versioning has never been enabled on the bucket.
  • When you upload an object with the same name as an existing object, the object is overwritten and the overwritten object is not retained or recoverable.
  • When you delete an object, the deletion is permanent and objects are not recoverable.

Enabled

If object versioning is enabled on a bucket:

  • When you upload an object with the same name as an existing object, the existing object becomes a previous version and the newly uploaded object becomes the latest object.

  • Each uploaded object version is assigned a unique version identifier. The identifier lets you direct Object Storage actions to a specific version.
  • When you delete an object, Object Storage retains a version of the deleted object. For more information about object deletion, see Understanding Object and Object Version Deletion.
  • You cannot disable object versioning. You can, however, suspend versioning.

Suspended

If object versioning is suspended on a bucket:

  • Upload and delete behavior is the same as a bucket that has versioning disabled.
  • Object versions created before versioning suspension are retained, unless you take explicit action to delete them.
  • You can re-enable object versioning at any time.

Understanding Object and Object Version Deletion

No object is physically deleted from a bucket that has versioning enabled. When you delete an object, a special version called a delete marker is created that marks the deletion point. The delete marker contains only minimal metadata. Because there are other ways to recover a previous version (like copying it), you can simply delete the delete marker and the previous version becomes the live object.

When you upload an object with the same name as the delete marker, the uploaded object becomes the live object. The delete marker remains. There can be multiple delete markers for an object and you can recover any of the previously deleted objects.

Object version deletion is different. When you delete an object version, the version is permanently deleted. Permanent deletion also happens if you explicitly delete the latest version by version ID. All delete operations that target a specific object version ID permanently deletes the data.

Tip

We recommend that you delete old or unneeded object versions to reduce storage costs.

Required IAM Policies

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

If you're new to policies, see Getting Started with Policies and Common Policies.

For administrators:

  • You can create a rule that lets the specified IAM group manage Object Storage namespaces, buckets, and their associated objects in all compartments in the tenancy. For example, to let the IAM group StorageAdmins do everything in the tenancy:

    Allow group StorageAdmins to manage object-family in tenancy
  • Alternatively, you can create policies that reduce the scope of access. For example, you can create the policies to let the StorageAdmins group manage only buckets and objects in a compartment called ObjectStore in the tenancy:

    Allow group StorageAdmins to manage buckets in compartment ObjectStore
    Allow group StorageAdmins to manage objects in compartment ObjectStore
  • If you create more restrictive policies that grant individual permissions, BUCKET_UPDATE is required to enable versioning. Creating objects or object versions, overwriting existing objects, or deleting objects require the regular permissions necessary for those operations. OBJECT_VERSION_DELETE is required to delete object versions. For example, to allow a group called StorageSupport to manage Object Storage resources, but prevent that group from permanently removing previous object versions:

    Allow group StorageSupport to manage object-family in tenancy where request.permission != 'DeleteObjectVersion'

For more information about other alternatives for writing policies, see Details for Object Storage, Archive Storage, and Data Transfer.

Scope and Constraints

  • Versioning can be enabled on a bucket in the Standard (Object Storage) or Archive Storage tier.
  • Restoring an archived object is an in-place operation and does not create an object version.
  • You can rename an object, but you cannot rename an object version. Renaming an object creates a new object or object version.

Interaction Between Versioning and Other Object Storage Features

This section describes some key things you need to know about the interaction between object versioning and other Object Storage features.

Bucket Re-Encryption

Bucket re-encryption (using either Oracle or your own master encryption key) also re-encrypts any existing object versions.

Lifecycle Management

Lifecycle policies can archive objects, but not previous object versions. When Lifecycle policies delete an object, the current object becomes a previous version and a delete marker is created.

Copying Objects

If you copy an object to a different bucket, only the object is copied. None of the object versions are copied. You can also copy a previous version of an object to another bucket, but that action creates a new object or object version in the destination bucket.

Replication

  • Replication cannot replicate previous object versions.
  • You cannot enable versioning on a replication destination bucket. A destination bucket is read-only.

Retention Rules

  • You cannot add retention rules to a bucket that has versioning enabled.
  • You cannot enable versioning on a bucket with active retention rules.
  • You can add retention rules to bucket that has versioning suspended. However, you cannot resume versioning with active retention rules.

Troubleshooting Versioning

This topic provides troubleshooting solutions for issues you might encounter using versioning.

Unable to enable versioning
Unable to delete a bucket
Unable to delete an object version

Using the Console

To enable versioning during bucket creation
To enable object versioning after bucket creation
To suspend object versioning
To re-enable object versioning from suspension
To view the list of object versions
To view the details of an object version
To delete an object or object version
To recover a deleted object

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

To determine the object versioning status for a bucket
To enable versioning during bucket creation
To enable object versioning after bucket creation
To list object versions
To get the contents of an object version
To delete an object version

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following API operations to enable object versioning:

Use the following API operation to list object versions:

To perform version-specific operations, use the following APIs with a version identifier query parameter:

Object-related APIs that do not take a version identifier query parameter operate only on an object, not object versions.