1. User Guide
  2. Object Storage
  3. Managing Object Versioning

Managing Object Versioning

Object versioning provides data protection against accidental or malicious object updates, overwrites, or deletions.

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.

For more conceptual information, refer to the Object Storage Overview section in the Oracle Private Cloud Appliance Concepts Guide.

Enabling Versioning During Bucket Creation

Object versioning provides data protection against accidental or malicious object updates and deletions.

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Syntax (entered on a single line):

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

    Example:

    oci os bucket create    \
--namespace-name examplenamespace  \
--compartment-id ocid.compartment.….….….exampleuniqueID    \
--name MyStandardBucket    \
--versioning enabled

{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid1.compartment.….….….uniqueID",
    "created-by": "ocid1.user.….….….uniqueID",
    "defined-tags": null,
    "etag": "00b4edbb27012ae78a912428ad1e630c",
    "freeform-tags": null,
    "id": null,
    "is-read-only": null,
    "kms-key-id": null,
    "metadata": null,
    "name": "bucket-4-versioning",
    "namespace": "export/examplenamespace",
    "object-events-enabled": null,
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": null,
    "storage-tier": "Standard",
    "time-created": "2021-06-10T18:39:12+00:00",
    "versioning": "Enabled"
  },
  "etag": "00b4edbb27012ae78a912428ad1e630c"
}

Enabling or Suspending Versioning (After Bucket Creation)

Object versioning provides data protection against accidental or malicious object updates and deletions.

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run the command.

    Syntax (entered on a single line):

    oci os bucket update
--namespace-name <object_storage_namespace> 
--compartment-id <target_compartment_id> 
--bucket-name <bucket_name> 
--versioning <enabled | suspended>

    For --versioning, choose one of the options: enabled or suspended.

    Example of enabling object versioning:

    oci os bucket update    \
--namespace-name examplenamespace  \
--compartment-id ocid.compartment.….….….uniqueID    \
--bucket-name MyBucket    \
--versioning Enabled
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid1.compartment.….….….uniqueID",
    "created-by": "ocid1.user.….….….uniqueID",
    "defined-tags": null,
    "etag": "117f0608bdf83b9c7ea393db556a0ee4",
    "freeform-tags": null,
    "id": null,
    "is-read-only": null,
    "kms-key-id": null,
    "metadata": null,
    "name": "MyBucket",
    "namespace": "export/examplenamespace",
    "object-events-enabled": null,
    "object-lifecycle-policy-etag": null,
    "public-access-type": "ObjectRead",
    "replication-enabled": null,
    "storage-tier": "Standard",
    "time-created": "2021-06-02T17:06:18+00:00",
    "versioning": "Enabled"
  },
  "etag": "117f0608bdf83b9c7ea393db556a0ee4"
}

Viewing Object Versions and Details

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run the command.

    Syntax (entered on a single line):

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

    Example:

    oci os object list-object-versions    \
--namespace-name examplenamespace  \
--bucket-name MyBucket
{
  "data": [
    {
      "etag": null,
      "is-delete-marker": false,
      "md5": "3DI5GbLmKiRxY/ozWxyXHQ==",
      "name": "bucket-data",
      "size": 103,
      "time-created": "2021-06-02T22:20:25+00:00",
      "time-modified": null,
      "version-id": null
    },
    {
      "etag": null,
      "is-delete-marker": false,
      "md5": "VIic5JncRWwDQj6CnsZ1Ww==",
      "name": "compute.log",
      "size": 4878456,
      "time-created": "2021-06-10T19:03:26+00:00",
      "time-modified": null,
      "version-id": "5f4ce7e8-656f-409a-b70a-ebfedddcfeda"
    }
  ],
  "prefixes": []
}

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

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Syntax:

    Note:

    If an object has a version-id of null, there is only one version of the object. To delete this object, omit the --version-id argument. 

    oci os object delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>
--version-id <bucket_version_id>
--object-name <object_name>

    Example:

    oci os object delete
--namespace-name examplenamespace  \ 
--bucket-name MyBucket  \
--version-id 7f1f537d-ec9c-4706-867a-b1dae355c263   \
--object-name compute.log

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

Using the OCI CLI

  1. List the objects in the bucket. See Viewing Object Versions and Details. In the output, locate the object version that has "is-delete-marker": true.

    Use the version-id of that object with the delete command to delete the delete marker.

    Note:

    If an object has a version-id of null, there is only one version of the object. To delete this object marker, omit the --version-id argument.

  2. Gather the information you need to run the command.

  3. Syntax:

    oci os object delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>
--object-name <object_name>
--version-id <bucket_version_id>

    Example:

    oci os object delete
--namespace-name examplenamespace  \ 
--bucket-name  MyBucket
--object-name application.log
--version-id  6ce3eb93-8850-4732-8949-cb6e67b722b0
Are you sure you want to delete this resource? [y/N]: y