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 latest object versions and previous object versions (including deleted versions) stored in the bucket. Previous object versions are retained until you explicitly delete them.

Object versioning does increase your storage costs. Consider using Object Lifecycle Management to help you manage object versions automatically.

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.

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

  • Each uploaded object 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 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 Version Deletion

No object is physically deleted from a bucket that has versioning enabled until you take explicit action to do so. When you delete an object without targeting a specific version, the latest object version becomes a previous object version and a special delete marker is created that marks the deletion point. A delete marker contains only minimal metadata. If you delete a folder, a delete marker is created for each object in the folder. You can simply delete the delete marker to make that deleted version become the latest object version.

When you upload an object with the same name as the delete marker, the uploaded object becomes the latest version of the object. The delete marker remains. There can be multiple delete markers for an object and you can recover any of the previous object versions.

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.

Required IAM Policies

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have 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 policy 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. Uploading objects, 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 object versions:
    Allow group StorageSupport to manage object-family in tenancy where request.operation != '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 the latest version of an object, but you cannot rename a previous object version. Renaming an object creates a new object.

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 the latest version or previous versions of an object. When Lifecycle policies delete the latest version of an object, that object becomes a previous version and a delete marker is created. When Lifecycle policies delete a previous version of an object, that deletion is permanent.

Copying Objects

If you copy the latest version of an object to a different bucket, only the object is copied. None of the object's previous versions are copied. You can copy a previous version of an object to another bucket, but that action creates either the latest version of a new object or a new 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

If enabling versioning fails, the most likely cause is missing or incomplete IAM permissions. Enabling versioning requires:

  • User permissions that let you use the bucket and manage the objects in that bucket.
  • Minimally, BUCKET_UPDATE permissions.

Review the existing policies that grant user permissions. For more information, see Required IAM Policies.

Unable to delete a bucket
If deleting a bucket fails, the most likely cause is that the bucket is not empty.
Caution

You cannot recover a deleted bucket.

You can permanently delete an empty bucket. You cannot delete a bucket that contains any of the following:

  • Any objects
  • Previous versions of an object
  • A multipart upload in progress
  • A pre-authenticated request
Tip

When you delete an object in a version-enabled bucket, a previous version of that object is created. Select Show Deleted Objects to display the object versions that might prevent you from deleting the bucket.
Unable to delete a previous object version

If deleting a previous object version fails, the most likely cause is missing or incomplete IAM permissions. Object version deletion requires:

  • User permissions that let you use the bucket and manage the objects in that bucket.
  • Minimally, OBJECT_VERSION_DELETE permissions.

Using the Console

To enable versioning during bucket creation
  1. Follow the steps for creating a bucket.
  2. Select Enable Object Versioning to direct Object Storage to create an object version each time the content changes or the object is deleted.
To enable object versioning after bucket creation
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the bucket that you want to enable object versioning.
  4. Click the bucket name.
  5. In Bucket Information, locate Object Versioning.

    Object Versioning indicates the current versioning status. Versioning is disabled by default. If you did not enable object versioning during bucket creation, Object Versioning is Disabled.

  6. Click Edit.
  7. Click Enable Versioning.
To suspend object versioning
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the bucket that you want to suspend object versioning.
  4. Click the bucket name.
  5. In Bucket Information, locate Object Versioning.

    Object Versioning indicates the current versioning status. Versioning is Enabled.

  6. Click Edit.
  7. Click Suspend Versioning.
To re-enable object versioning from suspension
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the bucket that you want to re-enable object versioning.
  4. Click the bucket name.
  5. In Bucket Information, locate Object Versioning.

    Object Versioning indicates the current versioning status. Versioning is Suspended.

  6. Click Edit.
  7. Click Enable Versioning.
To view the latest version of an object
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the bucket that you want to see the list of object versions.
  4. Click the bucket name.
  5. Click Objects under Resources.

  6. Expand any folders and subfolders as needed to find the object for which you want to display previous versions.

    The latest version of each object is displayed.

To view the previous versions of an object
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the bucket that you want to see the list of object versions.
  4. Click the bucket name.
  5. Click Objects under Resources.

  6. Expand any folders and subfolders as needed to find the object for which you want to display previous versions.

    The latest version of each object is displayed.

  7. Locate the object for which you want to display previous versions.

  8. Click the file expander, located to the left of the the Actions icon (three dots).

    Screenshot illustrating the file expansion widget displayed in the Console.

    The list of all previous versions of the object is displayed.

    Screenshot showing a list of object versions displayed in the Console.

To view the details of an object version
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the bucket that has the object version that you want to delete.
  4. Click the bucket name.
  5. Click Objects under Resources.

    A list of folders and the latest versions of objects in the bucket are displayed.

  6. Expand any folders and subfolders as needed to locate the object for which you want to view details.
  7. To display the details for the latest version of an object, click the Actions icon (three dots) to the right of the object, and then click View Object Details.
  8. To display the details for a previous version of an object, click the file expander, located to the left of the the Actions icon (three dots).

    Screenshot illustrating the file expansion widget displayed in the Console.

    The list of all previous versions of the object is displayed.

    Screenshot showing a list of object versions displayed in the Console.

  9. Click the Actions icon (three dots) to the right of the object version, and then click View Object Details.
To delete an object

When versioning is enabled, deleting an object without targeting a specific version creates a delete marker and a previous version of the object that can be recovered.

  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the bucket that has the object that you want to delete.
  4. Click the bucket name.
  5. Click Objects under Resources.

    A list of folders and objects in the bucket are displayed.

  6. Expand any folders and subfolders as needed to locate the object that you want to delete.
  7. Click the Actions icon (three dots) to the right of the object, and then click Delete.
  8. Confirm the deletion when prompted.
To delete the previous version of an object

When versioning is enabled, deleting an object without targeting a specific version creates a delete marker and previous version of the object that can be recovered. However, deleting a previous version of an object is a permanent deletion.

  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the bucket that has the object version that you want to delete.
  4. Click the bucket name.
  5. Click Objects under Resources.

    A list of folders and objects in the bucket are displayed.

  6. Expand any folders and subfolders as needed to locate the object for which you want to delete a previous version.
  7. Click the file expander, located to the left of the the Actions icon (three dots).

    Screenshot illustrating the file expansion widget displayed in the Console.

    The list of all previous versions of the object is displayed.

    Screenshot showing a list of object versions displayed in the Console.

  8. Locate the previous version of the object that you want to delete.
  9. Click the Actions icon (three dots) to the right of the object version, and then click Delete.
  10. Confirm the deletion when prompted.
To recover a deleted object version

Recovering a deleted object version is as simple as deleting the delete marker that was created when you deleted the latest version of an object. The previous version of the object listed just below the delete marker is recovered and becomes the latest version of the object.

  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Ensure that the correct region is selected from the regions menu (shown at the top of the Console).
  3. In the List Scope section, select the compartment that contains the bucket that has the object version that you want to recover.
  4. Click the bucket name.
  5. Click Objects under Resources.

    A list of folders and objects in the bucket are displayed.

  6. Select Show Deleted Objects.
  7. Expand any folders and subfolders as needed to locate the object that you want to recover.
  8. Click the file expander, located to the located to the left of the the Actions icon (three dots) of the deleted object to display the versions that you can recover.
  9. Click the Actions icon (three dots) to the right of the delete marker of the object, and then click Delete.
  10. Confirm deletion when prompted.

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
oci os bucket get --namespace <object_storage_namespace> --name <bucket_name>

For example:


oci os bucket get --namespace MyNamespace --name MyBucket					
{
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid1.compartment.oc1..aaaaaaaamnk2ilreg5fkgu7rarfbbhdv3a5ji4eixxgkl4uprbqk6aefv5sq",
    "created-by": "ocid1.user.oc1..aaaaaaaah46lg3ueuftovn3urjgstlg4laxnre3djelu5jxy5uaqhgy7acgq",
    "defined-tags": {
      "Financials": {
        "key1": "nondefault"
      }
    },
    "etag": "79833b3f-89bd-41ac-bf86-0fbe331f3071",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1.phx.aaaaaaaa4feuzkcagy77lxujdneujoiza7rh2unbpzmwytinhwxymy5zk6uq",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-04-14T14:25:32.465000+00:00",
    "versioning": "Disabled"
  },
  "etag": "79833b3f-89bd-41ac-bf86-0fbe331f3071"
}
To enable versioning during bucket creation

To enable versioning in a Standard tier bucket, you do not need to explicitly set --storage-tier because a bucket is created in the standard Object Storage tier by default:

oci os bucket create --namespace <object_storage_namespace> --name <bucket_name> --compartment-id <target_compartment_id> --versioning enabled

For example:

oci os bucket create --namespace MyNamespace --name MyStandardBucket --compartment-id ocid.compartment.oc1..exampleuniqueID --versioning enabled
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid1.compartment.oc1..aaaaaaaamnk2ilreg5fkgu7rarfbbhdv3a5ji4eixxgkl4uprbqk6aefv5sq",
    "created-by": "ocid1.user.oc1..aaaaaaaah46lg3ueuftovn3urjgstlg4laxnre3djelu5jxy5uaqhgy7acgq",
    "defined-tags": {
      "Financials": {
        "key1": "nondefault"
      }
    },
    "etag": "a91fd091-e112-483e-8e23-2b5d11e3dc2d",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1.phx.aaaaaaaaqagwnd5foe23xhpqk6ts754igpuw5t7qrnapbmrv5tjiugvjvicq",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyStandardBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-04-14T14:14:08.421000+00:00",
    "versioning": "Enabled"
  },
  "etag": "a91fd091-e112-483e-8e23-2b5d11e3dc2d"
}				

To enable versioning in an Archive tier bucket, you must explicitly set --storage-tier Archive:

oci os bucket create --namespace <object_storage_namespace> --name <archivebucket_name> --compartment-id <target_compartment_id> --storage-tier Archive

For example:

oci os bucket create --namespace MyNamespace --name MyArchiveBucket --compartment-id ocid.compartment.oc1..exampleuniqueID --storage-tier Archive --versioning enabled
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid1.compartment.oc1..aaaaaaaamnk2ilreg5fkgu7rarfbbhdv3a5ji4eixxgkl4uprbqk6aefv5sq",
    "created-by": "ocid1.user.oc1..aaaaaaaah46lg3ueuftovn3urjgstlg4laxnre3djelu5jxy5uaqhgy7acgq",
    "defined-tags": {
      "Financials": {
        "key1": "nondefault"
      }
    },
    "etag": "5f19e314-68ad-4abf-9aa5-ae326bf83092",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1.phx.aaaaaaaaozijn7ktq42wmyyrsxacy5z7btiosoevlkmqvw5qz5vc56urg5ca",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyArchiveBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Archive",
    "time-created": "2020-04-14T14:20:43.842000+00:00",
    "versioning": "Enabled"
  },
  "etag": "5f19e314-68ad-4abf-9aa5-ae326bf83092"
}
To enable object versioning after bucket creation
oci os bucket update --namespace <object_storage_namespace> --name <bucket_name> --compartment-id <target_compartment_id> --versioning Enabled

For example:

oci os bucket update --namespace MyNamespace --name MyBucket --versioning Enabled
{  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid1.compartment.oc1..aaaaaaaamnk2ilreg5fkgu7rarfbbhdv3a5ji4eixxgkl4uprbqk6aefv5sq",
    "created-by": "ocid1.user.oc1..aaaaaaaah46lg3ueuftovn3urjgstlg4laxnre3djelu5jxy5uaqhgy7acgq",
    "defined-tags": {
      "Financials": {
        "key1": "nondefault"
      }
    },
    "etag": "b8578b95-f37f-401f-ac4f-057b980ef680",
    "freeform-tags": {},
    "id": "ocid1.bucket.oc1.phx.aaaaaaaabez242beorntix2tb4qfure2x7n3vpfmarcfqscrtgh3hplacg5q",
    "is-read-only": false,
    "kms-key-id": null,
    "metadata": {},
    "name": "MyBucket",
    "namespace": "MyNamespace",
    "object-events-enabled": false,
    "object-level-audit-mode": "Disabled",
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": false,
    "storage-tier": "Standard",
    "time-created": "2020-03-25T05:27:12.373000+00:00",
    "versioning": "Enabled"
  },
  "etag": "b8578b95-f37f-401f-ac4f-057b980ef680"
}
To list object versions

oci os object list-object-versions --namespace <object_storage_namespace> --bucket-name <bucket_name>

For example:


oci os object list-object-versions --namespace MyNamespace --bucket-name MyStandardBucket
{
  "data": {
    "items": [
      {
        "etag": null,
        "is-delete-marker": false,
        "md5": null,
        "name": "MyTextDocument.txt",
        "size": null,
        "time-created": null,
        "time-modified": "2020-04-14T22:18:08.777000+00:00",
        "version-id": "2d528a44-5b15-40dc-b303-20993d1ade66"
      },
      {
        "etag": null,
        "is-delete-marker": false,
        "md5": null,
        "name": "MyTextDocument.txt",
        "size": null,
        "time-created": null,
        "time-modified": "2020-04-14T22:17:10.371000+00:00",
        "version-id": "a175ddc0-cc86-425f-bc2e-9b9bcb9bff92"
      },
      {
        "etag": null,
        "is-delete-marker": false,
        "md5": null,
        "name": "MyTextDocument.txt",
        "size": null,
        "time-created": null,
        "time-modified": "2020-04-14T22:14:47.675000+00:00",
        "version-id": "8d8f06ef-e0c2-4435-bea6-f7c3ec80a444"
      }
    ],
    "prefixes": null
  }
}
To get the contents of an object version
oci os object get --name <object_name> --file path/to/file/name --version-id <version_identifier> --namespace <object_storage_namespace> --bucket-name <bucket_name>

For example, to retrieve the contents of an object version into a file called TextDocument.txt:

oci os object get --name MyTextDocument.txt --file C:\workspace\TextDocument.txt --version-id 2d528a44-5b15-40dc-b303-20993d1ade66 --namespace MyNamespace --bucket-name MyStandardBucket
To delete an object version
oci os object delete --name <object_name> --version-id <version_identifier> --namespace <object_storage_namespace> --bucket-name <bucket_name>

For example:

oci os object delete --name MyTextDocument.txt delete --version-id 8d8f06ef-e0c2-4435-bea6-f7c3ec80a444 --namespace MyNamespace --bucket-name MyStandardBucket 
Are you sure you want to delete this resource? [y/N]: y

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.