Defining Retention Rules

Retention rules provide immutable storage options for data written to Object Storage for data governance, regulatory compliance, and legal hold requirements. Retention rules can also protect your data from accidental or malicious writes or deletion. Retention rules can be locked to prevent rule modification and data deletion or modification even by administrators.

Retention rules are configured at the bucket level and are applied to all individual objects in the bucket.

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

Viewing Retention Rules and Details

Using the OCI CLI

Listing the Retention Rules for a Bucket

Gather the information you need to run the command.
- Namespace (see Obtaining the Object Storage Namespace)
- Bucket name (oci os bucket list), see Listing Buckets

Run the command.

Syntax:

oci os retention-rule list
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>

Example:

oci os retention-rule list  \
--namespace-name examplenamespace  \
--bucket-name MyBucket
{
  "data": {
    "items": [
      {
        "display-name": "RegulatoryCompliance",
        "duration": {
          "time-amount": 5,
          "time-unit": "YEARS"
        },
        "etag": "72be3a47de931cd50ad9d93c077def64",
        "id": "72be3a47de931cd50ad9d93c077def64",
        "time-created": "2021-06-10T22:24:21+00:00",
        "time-modified": "2021-06-10T22:24:21+00:00",
        "time-rule-locked": "2021-06-30T17:00:00+00:00"
      },
      {
        "display-name": "TempHold",
        "duration": {
          "time-amount": 30,
          "time-unit": "DAYS"
        },
        "etag": "344a9c205187408699b51c7769dc1bb4",
        "id": "344a9c205187408699b51c7769dc1bb4",
        "time-created": "2021-06-10T22:17:50+00:00",
        "time-modified": "2021-06-10T22:17:50+00:00",
        "time-rule-locked": null
      },
      {
        "display-name": "LegalHold",
        "duration": null,
        "etag": "bd8d8efb964d1025f4305c86de630a4f",
        "id": "bd8d8efb964d1025f4305c86de630a4f",
        "time-created": "2021-06-10T22:13:37+00:00",
        "time-modified": "2021-06-10T22:13:37+00:00",
        "time-rule-locked": null
      }
    ]
  }
}

Getting Details for a Specific Retention Rule

Gather the information you need to run the command.
- Namespace (see Obtaining the Object Storage Namespace)
- Bucket name (oci os bucket list), see Listing Buckets
- Retention rule ID (oci os retention-rule list), see Viewing Retention Rules and Details

Run the command.

Syntax:

oci os retention-rule get
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--retention-rule-id <retention_rule_identifier>

Example:

oci os retention-rule get  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--retention-rule-id 72be3a47de931cd50ad9d93c077def64

{
  "data": {
    "display-name": "RegulatoryCompliance",
    "duration": {
      "time-amount": 5,
      "time-unit": "YEARS"
    },
    "etag": "72be3a47de931cd50ad9d93c077def64",
    "id": "72be3a47de931cd50ad9d93c077def64",
    "time-created": "2021-06-10T22:24:21+00:00",
    "time-modified": "2021-06-10T22:24:21+00:00",
    "time-rule-locked": "2021-06-30T17:00:00+00:00"
  }
}

Creating a Retention Rule

Using the OCI CLI

Creating an Indefinite Retention Rule

Gather the information you need to run the command.
- Namespace (see Obtaining the Object Storage Namespace)
- Bucket name (oci os bucket list), see Listing Buckets
- Display name: The name you want to apply to this retention rule.

Run this command.

Syntax:

oci os retention-rule create
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--display-name <name_displayed_for_rule>

Example:

oci os retention-rule create   \
--namespace-name examplenamespace  \
--bucket-name MyBucket   \
--display-name LegalHold
{
  "data": {
    "display-name": "LegalHold",
    "duration": null,
    "etag": "bd8d8efb964d1025f4305c86de630a4f",
    "id": "bd8d8efb964d1025f4305c86de630a4f",
    "time-created": "2021-06-10T22:13:37+00:00",
    "time-modified": "2021-06-10T22:13:37+00:00",
    "time-rule-locked": null
  }
}

Creating a time-bound, Unlocked Retention Rule

Gather the information you need to run the command.
- Namespace (see Obtaining the Object Storage Namespace)
- Bucket name (oci os bucket list), see Listing Buckets
- Display name: The name you want to apply to this retention rule.
- Time and unit(days|years). For example, 30 days or 5 years.

Run this command.

Syntax:

oci os retention-rule create
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--display-name <display_name> 
--time-amount <time_integer> 
--time-unit <days|years>

Example:

 oci os retention-rule create  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--display-name TempHold  \
--time-amount 30  \
--time-unit days
{
  "data": {
    "display-name": "TempHold",
    "duration": {
      "time-amount": 30,
      "time-unit": "DAYS"
    },
    "etag": "344a9c205187408699b51c7769dc1bb4",
    "id": "344a9c205187408699b51c7769dc1bb4",
    "time-created": "2021-06-10T22:17:50+00:00",
    "time-modified": "2021-06-10T22:17:50+00:00",
    "time-rule-locked": null
  }
}

Creating a Time-Bound, Locked Retention Rule

Gather the information you need to run the command.
- Namespace (see Obtaining the Object Storage Namespace)
- Bucket name (oci os bucket list), see Listing Buckets
- Display name: The name you want to apply to this retention rule.
- Time and unit (days|years). For example, 30 days or 5 years.
- Date and time to lock the rule.

Run this command.

Syntax:

oci os retention-rule create
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--display-name <display_name> 
--time-amount <time_integer> 
--time-unit <days|years> 
--time-rule-locked <date and time>

Example:

oci os retention-rule create  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--display-name RegulatoryCompliance   \
--time-amount 5   \
--time-unit years   \
--time-rule-locked "2021-06-30 17:00"
{
  "data": {
    "display-name": "RegulatoryCompliance",
    "duration": {
      "time-amount": 5,
      "time-unit": "YEARS"
    },
    "etag": "72be3a47de931cd50ad9d93c077def64",
    "id": "72be3a47de931cd50ad9d93c077def64",
    "time-created": "2021-06-10T22:24:21+00:00",
    "time-modified": "2021-06-10T22:24:21+00:00",
    "time-rule-locked": "2021-06-30T17:00:00+00:00"
  }
}

Modifying a Retention Rule

Using the OCI CLI

Updating a Retention Rule

Gather the information you need to run the command.
- Namespace (see Obtaining the Object Storage Namespace)
- Bucket name (oci os bucket list), see Listing Buckets
- Retention rule ID (oci os retention-rule list), see Viewing Retention Rules and Details

Run this command.

Syntax:

oci os retention-rule update
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--retention-rule-id <retention_rule_id>

Followed by the retention rule item that you plan to change:

--time-amount <time_integer> 
--time-unit <days|years>

Example:

oci os retention-rule update  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--retention-rule-id 344a9c205187408699b51c7769dc1bb4  \
--time-amount 60  \
--time-unit days 
{
  "data": {
    "display-name": "TempHold",
    "duration": {
      "time-amount": 60,
      "time-unit": "DAYS"
    },
    "etag": "344a9c205187408699b51c7769dc1bb4",
    "id": "344a9c205187408699b51c7769dc1bb4",
    "time-created": "2021-06-10T22:17:50+00:00",
    "time-modified": "2021-06-10T22:45:16+00:00",
    "time-rule-locked": null
  }
}

Removing a Retention Rule Lock During the Delay Period

Gather the information you need to run the command.
- Namespace (see Obtaining the Object Storage Namespace)
- Bucket name (oci os bucket list), see Listing Buckets
- Retention rule ID (oci os retention-rule list), see Viewing Retention Rules and Details

Run this command.

Syntax:

oci os retention-rule update
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--retention-rule-id <retention_rule_id>
--time-rule-locked ""

Example:

oci os retention-rule update
--namespace-name examplenamespace  \ 
--bucket-name MyBucket  \
--retention-rule-id b1a6c84c-57c4-416c-b006-f864b0904c9e 
--time-rule-locked ""
{
  "data": {
    "display-name": "RegulatoryCompliance",
    "duration": {
      "time-amount": 6,
      "time-unit": "YEARS"
    },
    "etag": "5b4fa526-faec-47d4-9162-4acdf1813ee0",
    "id": "b1a6c84c-57c4-416c-b006-f864b0904c9e",
    "time-created": "2020-03-25T15:11:44.423000+00:00",
    "time-modified": "2020-03-25T22:02:43.745000+00:00",
    "time-rule-locked": null
  },
  "etag": "5b4fa526-faec-47d4-9162-4acdf1813ee0"
}

Deleting a Retention Rule

Using the OCI CLI

Gather the information you need to run the command.
- Namespace (see Obtaining the Object Storage Namespace)
- Bucket name (oci os bucket list), see Listing Buckets
- Retention rule ID (oci os retention-rule list), see Viewing Retention Rules and Details

Syntax:

oci os retention-rule delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--retention-rule-id <retention_rule_identifier>

Example:

oci os retention-rule delete  \
--namespace-name examplenamespace  \
--bucket-name MyBucket   \
--retention-rule-id 344a9c205187408699b51c7769dc1bb4
Are you sure you want to delete this resource? [y/N]: y