Using Object Lifecycle Management

By using Object Lifecycle Management to manage your Object Storage and Archive Storage data, you can reduce your storage costs and the amount of time you spend manually managing data.

Object Lifecycle Management works by taking automated action based on rules that you define. These rules instruct Object Storage to delete uncommitted multipart uploads, move objects to a different storage tier, and delete supported resources on your behalf within a given bucket. A bucket's lifecycle rules are collectively known as an object lifecycle policy. The resources that Object Lifecycle Management supports include objects, object versions, and uncommitted or failed multipart uploads.

For example, you can define rules that automatically do things like the following:

Move Standard tier objects with a .doc extension to either the Infrequent Access or Archive tier 60 days after creation or last update.
Move Standard tier objects to the Archive tier 30 days after creation or last update, and then automatically delete those archived objects after 180 days.
Move Standard tier objects to the Infrequent Access tier 90 days after creation or last update.
Delete any previous object versions 120 days after the object version transitions from the latest version to a previous version.
Delete uncommitted or failed multipart uploads after 5 days.
Delete all objects and object versions in a bucket in preparation for bucket deletion.

Each Object Storage or Archive Storage bucket can have a single lifecycle policy consisting of up to 1,000 rules. Object-related rules can have object name prefix and pattern matching conditions. Uncommitted multipart upload rules do not support prefix and pattern matching conditions.

You can create, edit, delete, enable, and disable individual rules in the Console as needed. To update a lifecycle policy using the CLI or API, overwrite an existing policy with a new policy. Ensure that the new policy is inclusive of all the policy rules that you want to apply to the bucket.

Required IAM Policies

Important

You cannot use Object Lifecycle Management until you authorize the Object Storage service to archive and delete objects on your behalf. See Service Permissions for more information.

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

User Permissions

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 to work in.

For administrators:

The policy Let Object Storage admins manage buckets and objects lets the specified group do everything with buckets and objects, including adding and managing lifecycle policies.
If you create more restrictive policies that grant individual permissions:
- OBJECT_VERSION_DELETE is required to delete previous object versions on your behalf using lifecycle policies.
- OBJECT_UPDATE_TIER is required to change the storage tier of an object.

See Details for Object Storage, Archive Storage, and Data Transfer for more information on Object Storage user permissions.

Service Permissions

To execute object lifecycle policies, you must authorize the service to archive and delete objects on your behalf. To do so, create the following policy in the root compartment of your tenancy:

Allow service objectstorage-<region_identifier> to manage object-family in compartment <compartment_name>

Because Object Storage is a regional service, you must authorize the Object Storage service in each region you use lifecycle policies. Object Storage ensures that your data is not read from any unauthorized region.

If you don't have permissions to write policies for the root compartment of your tenancy, contact your Oracle Cloud Infrastructure administrator. To determine the region identifier value of an Oracle Cloud Infrastructure region, see Regions and Availability Domains.

Instead of using the policy verbmanage, you can grant individual permissions to the service. For example:

Allow service objectstorage-<region_identifier> to manage object-family in compartment <compartment_name> where any {request.permission='BUCKET_INSPECT', request.permission='BUCKET_READ', request.permission='OBJECT_INSPECT', request.permission='OBJECT_CREATE', request.permission='OBJECT_DELETE', request.permission='OBJECT_VERSION_DELETE'}

Options

When creating object lifecycle policy rules, you have the following options:

When a lifecycle rule is created, the system generates a default name for that rule, for example lifecycle-rule-20190321-1559. This rule name identifies the current year, month, day, and time that the rule was created. You can use that system-generated name for your new rule or you can specify a different name for it.
You can create lifecycle rules that do the following:
- Move or delete all objects in the bucket.
- Move or delete objects in the bucket that match the object name filters you specify. You can select objects using both object name prefixes and pattern matching. See Using Object Name Filters for details.
- Delete uncommitted or failed multipart uploads. For more information, see Using Multipart Uploads.
If object versioning is enabled or suspended on a bucket, you can also create lifecycle rules that do the following:
- Move or delete the previous versions of all objects in the bucket.
- Move or delete the previous versions of objects in the bucket that match the name filters you specify. You can select objects using both object name prefixes and pattern matching. See Using Object Name Filters for details.
You specify the number of days until the specified action is taken.
You decide whether a new rule is enabled or disabled upon creation.

Using Object Name Filters

Use object name filters to specify a subset of objects, object versions, or previous object versions that a lifecycle rule applies to. Create a separate object name filter rule for each rule target (objects, object versions, or previous object versions).

Important

Do not specify object name filters if you want a rule to apply to the all objects, all object versions, or all previous object versions target.

Two types of object name filters are supported:

Prefix matching is an exact matching of the left-most characters of an object name. Prefix matching does not support wildcard characters. While Object Storage buckets and objects exist in a flat structure, prefixes let you simulate a directory structure when used with a slash (/). See Object Naming Using Prefixes and Hierarchies for details.
Pattern matching matches on the entire object name, but supports using wildcard characters and other pattern matching constructs as needed to match zero or more characters within the object name.

Important

Object name filters operate on the entire object name. Prefixes (displayed as virtual folders and subfolders in the Console) are part of the object name.

Screenshot showing how virtual folders appear in the Console.

In this illustration, /marathon/participants/p_21.jpg is the name of the object, not p_21.jpg.

You can add object name filters in any order. Object Lifecycle Management evaluates the precedence of the rules as follows:

Pattern exclusions
Pattern inclusions
Prefix inclusions

Using Prefix Matching to Filter Objects

You can use prefix strings for matching purposes when performing lifecycle management-related operations. Certain bulk operations can also be performed by matching on the prefix portions of the object name.

In the following object name examples, prefixes include one or more forward slashes (/) to simulate a directory structure. The string marathon/ or marathon/participants/ can serve as a prefix for matching purposes in lifecycle rules:
```
marathon/finish_line.jpg
marathon/podium.jpg
marathon/participants/p_21.jpg
marathon/participants/p_29.jpg
```
In the following object name examples, the string gloves_27_ can serve as a prefix for matching purposes in lifecycle rules:
```
gloves_27_dark_green.jpg
gloves_27_light_blue.jpg
gloves_27_deep_purple.jpg
gloves_27_bright_orange.jpg
        
```

Using Pattern Matching to Filter Objects

Object Storage supports the following pattern matching characters to either include or exclude objects:


Character	Description	Pattern Examples	Matches	Doesn't Match
*	Matches 0 or more characters	*.tmp	foo.tmp foo/bar/baz.tmp	tmp Atmp
		*.xls	.xls /home/user/file.xls	xls .xl
		/archive/*	/archive/sub/dir/ /archive/1/2/3/4/foo.txt	/src/archive/a archive/b
?	Matches any one character	X?Z	XyZ X_Z	XZ XYYZ
\	Escapes the next character	\\dir\\sub\\*	\dir\sub\ABC \dir\sub\	dir\sub\abc dirsub
[...]	Matches a group of characters, which can be: A set of characters, for example: [Zafg9@]. Matches any character in the brackets. A range of characters, for example: [a-f]. Matches any character in the range: [a-f] is equivalent to [abcdef]. For character ranges only the CHARACTER-CHARACTER pattern is supported: [ab-yz] is not valid. [a-mn-z] is not valid. Character ranges cannot start with ^ or colon (:). To include a hyphen (-) in the range, make it the first or last character.	[-ab3]	- a b 3	-a -ab 3b
		backup.tar.gz.[0-9]	backup.tar.gz.0 backup.tar.gz.5 backup.tar.gz.9	backup.tar.gz10 backup.tar.gz
		page-[0-9]*	page-0 page-2 page-22 page-2X	page- page-A1
		\[a-z\]	[a-z]	a z [a-z

Patterns are limited to 1024 characters. The following are examples of invalid patterns:

\
[^a-z]
[z-a]
[:isalpha:]

Scope and Constraints

Understand the following scope and constraints regarding object lifecycle policy rules:

When you create a lifecycle policy rule, that rule applies to all objects, all object versions, or all previous object versions that exist in the bucket unless you add object name filters for that target.
Prefix and pattern matching filtering applies only to rules for objects, object versions, or previous object versions. Object filtering does not apply to uncommitted multipart uploads.
A rule that deletes an object always takes priority over a rule that would move that same object to another storage tier.
When you create a rule that moves or deletes previous object versions, you specify the number of days until the move or deletion occurs. The "number of days" countdown is based on when the object version transitioned from being the latest object version to being a previous object version. This time can be determined by looking at the "last modified" time of the preceding most recent version of the object. The following screenshot illustrates the time used to start the countdown for archival or deletion in the Console.
If Auto-Tiering is enabled, you cannot create a rule that moves objects, object versions, or previous object versions to Infrequent Access.
Be aware of minimum retention periods when you create rules that move or delete the latest version or previous versions of objects.
- The Archive tier has a minimum retention requirement of 90 days. Objects moved or deleted from the Archive tier that have not met the 90-day retention minimum are billed for 90 days of storage.
- Infrequent Access tier has a minimum retention requirement of 31 days. Objects moved or deleted from the Infrequent Access tier that have not met the 31-day retention minimum are billed for 31 days of storage.
You can create up to 1,000 lifecycle rules per bucket.

Working with Object Lifecycle Management Policies

You can create, delete, edit, or disable lifecycle policy rules using the Console, the Command Line Interface (CLI), an SDK, or the API.

Caution

Objects deleted on your behalf by lifecycle policies cannot be recovered. Be sure when creating and editing your lifecycle policies that you are not unintentionally deleting data you want to retain. Oracle recommends that you test your lifecycle policy on development data before using the policy in production.

Using the Console

To create a lifecycle policy rule

Open the navigation menu and click Storage. Under Object Storage, click Buckets.
Choose the compartment containing the bucket for which you want to create a lifecycle rule.
Click the bucket name.
Click Lifecycle Policy Rules under Resources to access the lifecycle policy rule list.
Click Create Rule.
The Console checks the IAM policies that are in place to ensure policy rule creation success. If you see a policy missing warning, you can let the Console try to create any missing policies or copy the missing policy details to the clipboard to email your administrator. If you think you have the required policies in place, go ahead and try to create the lifecycle policy rule.
Provide the following information:
- Name: Required. The system generates a default rule name that reflects the current year, month, day, and time, for example lifecycle-rule-20190321-1559. If you change this default to any other rule name, use letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.
- Target: Required. Select the target to which the lifecycle rule applies.
  - If object versioning is Disabled, select the rule target Objects or Uncommitted Multipart Uploads.
  - If object versioning is Enabled or , Suspended select the rule target Latest Version of Objects, Previous Versions of Objects, or Uncommitted Multipart Uploads.
- Lifecycle Action:
  - If the rule target is Objects, Latest Version of Objects, or Previous Versions of Objects, select Move to Archive, Move to Infrequent Access, or Delete.
    If Auto-Tiering is enabled on the bucket, Move to Infrequent Access is not available for selection.
  - If the rule target is Uncommitted Multipart Uploads, Delete is the only option and is selected by default.
- Number of Days: The number of days until the specified action is taken.
  
  Note
  
  If the rule archives or deletes a previous object version, the "number of days" countdown is based on when the object version transitioned from being the latest object version to being a previous object version. This time can be determined by looking at the "last modified" time of the preceding most recent version of the object. The following screenshot illustrates the time used to start the countdown for archival or deletion in the Console.
If the rule target is Objects, Latest Version of Objects, or Previous Versions of Objects, you can optionally add one or more Object Name Filters to specify which objects the lifecycle rule applies to. You can choose objects or object versions using prefixes and pattern matching. If no object name filters are specified, the rule applies to all objects in the bucket.

To create an object name filter:
1. Click Add Filter.
2. Select the Filter Type.
3. Enter the Filter Value.
4. Click Add Another Filter to add as many filters as you need for this rule.
Select whether the rule is enabled or disabled upon creation using the State selector.
Click Create.

To edit a lifecycle policy rule

Open the navigation menu and click Storage. Under Object Storage, click Buckets.
Choose the compartment containing the bucket for which you want to edit a lifecycle rule.
Click the bucket name.
Click Lifecycle Policy Rules under Resources to access the rule list.
Click the Actions icon (three dots) to the right of the rule that you want to edit, and then click Edit.
In the Edit Lifecycle Rule dialog box, edit the following as needed for each rule you want to change.
- Name: A user-friendly name for the rule. Avoid entering confidential information.
- Lifecycle Action:
  - If the rule target is Objects, Latest Version of Objects, or Previous Versions of Objects, select Move to Archive, Move to Infrequent Access, or Delete.
  - If the rule target is Uncommitted Multipart Uploads, Delete is the only option and is selected by default.
- Number of Days: The number of days until the specified action is taken.
- If the rule pertains to objects or object versions, you can edit, delete, or add prefix or pattern Object Name Filters.
- Enable or disable the rule using the State selector.
Click Save Changes.

To enable, disable, or delete a lifecycle policy rule

You can enable, disable, or delete a rule using the Console. The system stops the execution of disabled or deleted rules immediately.

Open the navigation menu and click Storage. Under Object Storage, click Buckets.
Choose the compartment containing the bucket for which you want to enable, disable, or delete a lifecycle rule.
Click the bucket name.
Click Lifecycle Policy Rules under Resources to access the rule list.
Click the Actions icon (three dots) to the right of the rule that you want to manage, and then click one of the following:
- Enable (only displays if the rule is disabled)
- Disable (only displays if the rule is enabled)
- Delete

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 create or replace a lifecycle policy for a bucket

Note

To edit an existing lifecycle policy using the CLI, you need to replace the policy with a new complete version that includes all changed rules.

oci os object-lifecycle-policy put --namespace <object_storage_namespace> --bucket-name <bucket_name> --items <json_formatted_lifecycle_policy>

Tip

The --items option requires that you provide key-value pair input as valid formatted JSON. See Passing Complex Input and Using a JSON File for Complex Input for information about JSON formatting.

The --items key-value pair input must specify the following:

[
    {
      "action": "string",
      "isEnabled": true,
      "name": "string",
      "objectNameFilter": {
        "exclusionPatterns": [
          "string",
          "string"
        ],
        "inclusionPatterns": [
          "string",
          "string"
        ],
        "inclusionPrefixes": [
          "string",
          "string"
        ]
      },
      "target": "string",
      "timeAmount": 0,
      "timeUnit": "string"
    }
  ]

Specify one of the following values for action:


Value	Description
`ARCHIVE`	Specify this action to move objects, object versions, or previous object versions to the Archive tier.
`INFREQUENT_ACCESS`	Specify this action to move objects, object versions, or previous object versions to the Infrequent Access tier. If Auto-Tiering is enabled on the bucket, you cannot specify `INFREQUENT_ACCESS`.
`DELETE`	Specify this action to delete objects, object versions, or object versions.
`ABORT`	Use this action to delete failed or incomplete multipart uploads.

Specify one of the following values for target:


Value	Description
`objects`	Use this action to move objects, object versions, or previous object versions to the Archive tier.
`object-versions`	Use this action to move objects, object versions, or previous object versions to the Infrequent Access tier.
`multipart-uploads`	Use this action to delete objects, object versions, or previous object versions.

Specify timeUnit in days.

The following example creates or replaces a lifecycle policy that includes a rule for moving previous object versions with names that include the pattern *.doc from the Standard tier to the Archive tier after 60 days. The policy also includes a rule that deletes previous object versions after 180 days.

oci os object-lifecycle-policy put --namespace MyNamespace --bucket-name MyStandardBucket --items
'[
      {
        "action": "ARCHIVE",
        "is-enabled": true,
        "name": "Move-to-Archive-Rule",
        "object-name-filter": {
          "exclusion-patterns": null,
          "inclusion-patterns": [
            "*.doc"
          ],
          "inclusion-prefixes": null
        },
        "target": "previous-object-versions",
        "time-amount": 60,
        "time-unit": "DAYS"
      },
      {
        "action": "DELETE",
        "is-enabled": true,
        "name": "Delete-Rule",
        "object-name-filter": {
          "exclusion-patterns": null,
          "inclusion-patterns": [
            "*.doc"
          ],
          "inclusion-prefixes": null
        },
        "target": "previous-object-versions",
        "time-amount": 180,
        "time-unit": "DAYS"
      }
]'

The following example creates or replaces a lifecycle policy that includes a rule for moving all objects from the Standard tier to the Infrequent Access tier after 45 days. The policy also includes a rule that moves all objects to the Archive tier after 90 days.

oci os object-lifecycle-policy put --namespace MyNamespace --bucket-name MyStandardTierBucket --items
'[
      {
        "action": "INFREQUENT_ACCESS",
        "is-enabled": true,
        "name": "Move-to-Infrequent-Access-Rule",
        "object-name-filter": null,
        "target": "objects",
        "time-amount": 45,
        "time-unit": "DAYS"
      },
      {
        "action": "ARCHIVE",
        "is-enabled": true,
        "name": "Move-to-Archive-Rule",
        "object-name-filter": null,
        "target": "objects",
        "time-amount": 90,
        "time-unit": "DAYS"
      }
]'

The following example creates or replaces a lifecycle policy rule that deletes previous object versions from the Archive tier after 240 days.

oci os object-lifecycle-policy put --namespace MyNamespace --bucket-name MyArchiveTierBucket --items
'[
    {
        "action": "DELETE", 
        "is-enabled": true, 
        "name": "Delete-from-Archive-Rule", 
        "object-name-filter": null,
        "target": "previous-object-versions",
        "time-amount": 240, 
        "time-unit": "DAYS"
      }
]'

The following example creates or replaces a lifecycle policy rule that deletes all uncommitted or failed multipart uploads after 5 days:

oci os object-lifecycle-policy put --namespace MyNamespace --bucket-name MyBucket --items
'[
    {
        "action": "ABORT", 
        "is-enabled": true, 
        "name": "Delete-Failed-Multipart-Uploads-Rule", 
        "object-name-filter": null,
        "target": "multipart-uploads",
        "time-amount": 5, 
        "time-unit": "DAYS"
      }
]'

Instead of using the --items option, you can pass the JSON key-value pairs in a file. For example:

oci os object-lifecycle-policy put --namespace MyNamespace --bucket-name MyStandardTierBucket --file /path/to/file/filename

On Windows, to pass complex input to the CLI as a JSON string, you must enclose the entire block in double quotes. Inside the block, each double quote for the key and value strings must be escaped with a backslash (\) character.

For example:

oci os object-lifecycle-policy put --namespace MyNamespace --bucket-name MyStandardTierBucket --items "[{\"action\":\"ARCHIVE\",\"isEnabled\":true,\"name\":\"move-to-Archive-rule\",\"target\":\"previous-object-versions\",\"timeAmount\":180,\"timeUnit\":\"DAYS\"}]"

To delete a bucket's lifecycle policy

Deletes all of the lifecycle policy rules that you have defined for the specified bucket.

oci os object-lifecycle-policy delete --namespace <object_storage_namespace> --bucket-name <bucket_name>

For example:

oci os object-lifecycle-policy delete --namespace MyNamespace --bucket-name MyStandardTierBucket

When prompted, confirm the deletion.

To get a bucket's lifecycle policy

Gets all of the lifecycle policy rules that you have defined for the specified bucket.

oci os object-lifecycle-policy get --namespace <object_storage_namespace> --bucket-name <bucket_name>

For example:

oci os object-lifecycle-policy get --namespace MyNamespace --bucket-name MyStandardTierBucket{
  "data": {
    "items": [
      {
        "action": "ABORT",
        "is-enabled": true,
        "name": "Delete-Failed-Multipart-Uploads-Rule",
        "object-name-filter": null,
        "target": "multipart-uploads",
        "time-amount": 5,
        "time-unit": "DAYS"
      },
      {
        "action": "DELETE",
        "is-enabled": true,
        "name": "Delete-from-Archive-Rule",
        "object-name-filter": {
          "exclusion-patterns": null,
          "inclusion-patterns": null,
          "inclusion-prefixes": null
        },
        "target": "objects",
        "time-amount": 240,
        "time-unit": "DAYS"
      },
      {
        "action": "INFREQUENT_ACCESS",
        "is-enabled": true,
        "name": "Move-to-Infrequent-Access-Rule",
        "object-name-filter": {
          "exclusion-patterns": null,
          "inclusion-patterns": null,
          "inclusion-prefixes": null
        },
        "target": "objects",
        "time-amount": 45,
        "time-unit": "DAYS"
      },
      {
        "action": "ARCHIVE",
        "is-enabled": true,
        "name": "Move-to-Archive-Rule",
        "object-name-filter": {
          "exclusion-patterns": null,
          "inclusion-patterns": null,
          "inclusion-prefixes": null
        },
        "target": "previous-object-versions",
        "time-amount": 90,
        "time-unit": "DAYS"
      }
    ],
    "time-created": "2021-02-01T15:34:59.007000+00:00"
  },
  "etag": "009743fb-9503-4442-913f-fddd2ebd9542"
}

For example, to get the lifecycle policy that archives objects after 30 days:

oci os object-lifecycle-policy get --namespace MyNamespace --bucket-name MyBucketWithoutVersioning
{
  "data": {
    "items": [
      {
        "action": "ARCHIVE",
        "is-enabled": true,
        "name": "Archive-After-30-Days-Rule",
        "object-name-filter": {
          "exclusion-patterns": null,
          "inclusion-patterns": null,
          "inclusion-prefixes": null
        },
        "target": "objects",
        "time-amount": 30,
        "time-unit": "DAYS"
      }
    ],
    "time-created": "2020-10-27T17:56:27.085000+00:00"
  },
  "etag": "lifecycle-policy-a3f5d4a6-ca25-4a28-9eea-7d073f51e754"
}

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 operations to manage object lifecycle policies:

Oracle Cloud Infrastructure Documentation

Using Object Lifecycle Management

Required IAM Policies

User Permissions

Service Permissions

Options

Using Object Name Filters

Using Prefix Matching to Filter Objects

Using Pattern Matching to Filter Objects

Scope and Constraints

Working with Object Lifecycle Management Policies

Using the Console

Using the Command Line Interface (CLI)

Using the API