Updated on 2024-07-24 GMT+08:00

Lifecycle Management

You can define a lifecycle rule to automatically delete a set of objects or transition them between storage classes after a certain number of days since the objects were last updated.

The object update time refers to when objects were uploaded or when objects became historical.

Figure 1 Lifecycle management diagram

Scenarios

You may configure lifecycle rules to:
  • Periodically delete logs that are only meant to be retained for a specific period of time (a week or a month).
  • Transition documents that are seldom accessed to the Infrequent Access or Archive storage class or delete them.
  • Store some types of data in OBS for archive purposes, such as digital media, financial and medical records, raw genome sequence data, long-term database backups, and data that must be retained for regulatory compliance.
  • Schedule the deletion of a large number of files from a bucket. Manually deleting objects is time-consuming, and only a limited number of objects can be deleted at a time.

You can define lifecycle rules to identify objects in the scenarios above and further manage their lifecycles.

Objects that are no longer frequently accessed can be transitioned to Infrequent Access or Archive or Deep Archive to reduce your storage costs. In short, transition basically means that the object storage class is altered without copying the object. You can also manually change the storage class of an object on the Objects page. For details, see Uploading a File.

Lifecycle configuration can be added to a bucket with versioning enabled or disabled. By default, versioning is disabled. You can enable it. A version-enabled bucket keeps a current object version and zero or more non-current object versions. You can use versioning and lifecycle configurations together to help reduce storage costs. The predefined lifecycle configuration actions can facilitate management over the lifecycle of the current object versions and non-current object versions.

Precautions

  • There is no limit on the number of lifecycle rules in a bucket, but the total size of XML descriptions about all lifecycle rules in a bucket cannot exceed 20 KB.
  • A maximum of 20 lifecycle rules can be configured for a parallel file system.
  • A lifecycle rule name contains only uppercase or lowercase letters, digits, periods (.), underscores (_), and hyphens (-).
  • The minimum storage duration is 180 days for Deep Archive storage, 90 days for Archive storage, and 30 days for Infrequent Access storage. After an object is transitioned to the Archive storage class, if it stays in this storage class for less than 90 days, you still need to pay for a full 90 days.
  • Restrictions on storage class transition:
    • Only transitions from the Standard storage class to the Infrequent Access storage class are supported. To transition objects from Infrequent Access to Standard, you must manually operate it.
    • Only transitions from the Standard or Infrequent Access storage class to the Archive storage class are supported. To transition objects from Archive to Standard or Infrequent Access, you must restore the archived objects first and then manually transition their storage class.
    • Only transitions from the Standard, Infrequent Access, or Archive storage class to the Deep Archive storage class are supported. To transition objects from Deep Archive to Standard, Infrequent Access, or Archive, you must restore the deep archived objects first and then manually transition their storage class.
    • Multi-AZ redundancy is not available for Archive or Deep Archive storage. For this reason, buckets or objects with multi-AZ redundancy cannot be transitioned to the Archive or Deep Archive storage class based on a lifecycle rule.
  • Object deletion upon expiration:

    You can use the Expiration action a lifecycle rule to expire an object when the object reaches the end of its lifetime. In a versioning-enabled bucket, you can also use the NoncurrentVersionExpiration action to expire non-current object versions.

    • In a bucket with versioning disabled, the Expiration action permanently deletes objects.
    • In a bucket with versioning enabled (or suspended), the Expiration action retains the current version as a non-current version by adding a delete marker, which then becomes the current version. The NoncurrentVersionExpiration action permanently deletes non-current object versions.
  • Beside buckets, you can also configure the expiration time for objects during object uploads. The expiration time of objects prevails against that of buckets.

    After an object expires, OBS adds the object to the deletion queue and delete it asynchronously. This may cause the deletion time to be later than the expiration time. After an object is deleted, you will no longer be billed for its storage.

    To query the planned expiration time of an object, you can call the GET object API or HEAD object API. These APIs return response headers that provide expiration information about the object.

  • In theory, it takes 24 hours at most to execute a lifecycle rule. After an object is updated, OBS calculates its lifecycle from the next 00:00 (UTC time), so there may be a delay of up to 48 hours in transitioning objects between storage classes or deleting expired objects. If you make changes to an existing lifecycle rule, the rule will take effect again.
  • After a lifecycle rule is modified, the modification does not apply to the objects that have already met the configured conditions. For example, the original lifecycle rule causes objects meeting the configured conditions expire and then be deleted after they are stored for one day. Under this rule, the objects uploaded on January 1, 2021 will be deleted on January 3, 2021. On January 3, 2021, if you change the lifecycle rule to delete objects after they are stored for seven days, the objects uploaded on January 1, 2021 will still be deleted on January 3, 2021, but this modification will apply to those uploaded on and after January 2, 2021.

Lifecycle Rules

Lifecycle rules have the following key elements:

  • Policy: Configure a lifecycle rule that takes effect on specified objects.
    • By prefix: You can specify an object name prefix, so the lifecycle rule will take effect on objects share the same prefix.
    • Entire bucket: You can specify an entire bucket, so the lifecycle rule will take effect on all objects in the bucket.
  • Time: a scheduled time when object storage class is transitioned
    You can specify the number of days after which objects that have been last updated and meet specified conditions are automatically transitioned to Infrequent Access or Archive or Deep Archive, or are automatically deleted upon expiration.
    • Transition to Infrequent Access: You can specify the number of days after which objects that have been last updated and meet specified conditions are automatically transitioned to Infrequent Access.
    • Transition to Archive: You can specify the number of days after which objects that have been last updated and meet specified conditions are automatically transitioned to Archive.
    • Transition to Deep Archive: You can specify the number of days after which objects that have been last updated and meet specified conditions are automatically transitioned to Deep Archive.
    • Deleted upon expiration: You can specify the number of days after which objects that have been last updated and meet specified conditions are automatically deleted.
    The lifecycle rule time has the following restrictions:
    • If only one transition is involved, the time should be at least one day later.
    • If multiple transitions are involved, the latter transition should be at least one day longer than the former transition.

      For example, if you want a lifecycle rule to change object storage class and delete expired objects, you can set the transition time to 23 days later and the deletion time to at least 24 days later.

      The minimum storage duration is 180 days for Deep Archive storage, 90 days for Archive storage, and 30 days for Infrequent Access storage. If objects are deleted by a lifecycle rule before they have been stored for this minimum duration, you still need to pay for a full 30 or 90 days.

      Assume that you have an object in the Standard storage class stored in a bucket and you no longer plan to perform any operations on the object. The lifecycle rule applied to this object changes the object from Standard to Infrequent Access three days later, then to Archive on the fourth day, and finally deletes the object when it expires seven days later. In this case, you will be charged for three days of Standard storage, 30 days of Infrequent Access storage, and 90 days of Archive storage.

Lifecycle Configuration Elements

You can set the lifecycle configuration format to XML. The configuration contains one or more lifecycle rules.

Each rule consists of the following contents:

  • Metadata, specifying the rule ID and whether the rule is enabled or disabled. If the rule is disabled, OBS does not perform any actions defined in the rule.
  • Filtering criteria, identifying objects on which lifecycle rules are applied. You can set the object name prefix to be the filtering criteria.
  • When (a date or a time period) will one transition or expiration action be performed on objects in the lifecycle.

Configuration examples:

Example 1: Lifecycle configuration for a bucket with versioning disabled

By default, versioning is disabled for buckets. In such case, each object in the bucket has only one version.

Assume that versioning is disabled for your bucket. If you want Standard objects whose name starts with documents/ to transition to the Infrequent Access storage class 30 days after they are uploaded, then transition from Infrequent Access to Archive 60 days after they are uploaded, and finally to be deleted one year after they are uploaded, you can add the following lifecycle configuration for your bucket. This configuration includes the Transition and Expiration actions and applies to objects whose key prefix is documents (specified in the Prefix element).

<LifecycleConfiguration> 
    <Rule> 
        <ID>sample-rule</ID> 
        <Prefix>documents/</Prefix> 
        <Status>Enabled</Status> 
        <Expiration> 
             <Days>365</Days> 
        </Expiration> 
        <Transition>  
             <Days>30</Days> 
             <StorageClass>WARM</StorageClass>
        </Transition>  
        <Transition>  
             <Days>60</Days>  
             <StorageClass>COLD</StorageClass>  
        </Transition> 
    </Rule> 
</LifecycleConfiguration>

Example 2: Lifecycle configuration for a bucket with versioning enabled

You can enable versioning for buckets. If versioning is enabled for a bucket, the bucket will retain the current object version and its non-current object versions. For details, see Versioning. Versioning control enables you to maintain the history records of objects and lifecycle management allows you to control the retention of object versions as well as the storage class transition.

For a bucket with versioning enabled, lifecycle configuration provides multiple predefined actions that can be used to manage non-current object versions. In this example, the lifecycle configuration has a rule that specifies two operations (NoncurrentVersionTransition and NoncurrentVersionExpiration) for objects whose key prefix is logs/. The NoncurrentVersionTransition action transitions objects to Infrequent Access and then to Archive 30 days and 60 days respectively after they become non-current versions. The NoncurrentVersionExpiration action permanently deletes objects 180 days after they become non-current versions.

<LifecycleConfiguration> 
    <Rule> 
        <ID>sample-rule</ID> 
        <Prefix>logs/</Prefix> 
        <Status>Enabled</Status>    
        <NoncurrentVersionExpiration>      
            <NoncurrentDays>180</NoncurrentDays>     
        </NoncurrentVersionExpiration> 
        <NoncurrentVersionTransition>  
            <NoncurrentDays>30</NoncurrentDays>  
            <StorageClass>WARM</StorageClass>  
        </NoncurrentVersionTransition>  
        <NoncurrentVersionTransition>  
            <NoncurrentDays>60</NoncurrentDays>  
            <StorageClass>COLD</StorageClass>  
        </NoncurrentVersionTransition> 
    </Rule> 
</LifecycleConfiguration>

You can use the predefined NoncurrentVersionTransition and NoncurrentVersionExpiration actions to manage non-current versions in your bucket.

Generally, each lifecycle rule consists of the following parts:

  • Metadata: specifying the rule ID (<ID> element) and whether the rule is enabled or disabled (<Status> element). If the rule is disabled, OBS does not perform any actions defined in the rule.
  • Prefix (<Prefix> element), which identifies objects to which the rule applies.
  • Actions that you want to perform on the specified objects (such as NoncurrentVersionTransition and NoncurrentVersionExpiration mentioned in the previous example). For each action, you must specify a date or time period.

Elements in the lifecycle configuration rule are described as follows:

  • Element ID

    A lifecycle configuration can have up to 1,000 rules. The ID element uniquely identifies a rule.

  • Element Status

    The value can be Enabled or Disabled. If a rule is disabled, OBS does not perform any actions defined in the rule.

  • Element Prefix

    A lifecycle rule applies to one or more objects with the name prefix specified in the rule. Suppose you have the following objects:

    • logs/day1
    • logs/day2
    • logs/day3
    • ExampleObject.jpg

      If you set Prefix to ExampleObject.jpg, the rule applies only to object ExampleObject.jpg. If you set Prefix to logs/, the rule applies to the objects whose name starting with logs/. If you leave Prefix blank, the rule applies to all objects in your bucket.

  • Element Action

    You can specify predefined actions in the lifecycle rule to perform them on your buckets in the lifecycle. The predefined actions include Transition, Expiration, NoncurrentVersionTransition, and NoncurrentVersionExpiration. The effect of these operations depends on the versioning status of your bucket.

    By default, versioning is disabled for buckets. You can enable it for your bucket as needed, so that each object in this bucket can have a current version and zero or more non-current versions. You can also suspend versioning. For details, see Versioning.

  • Action Transition

    This action archives objects by changing object storage class to Infrequent Access or Archive or Deep Archive. When the date or time period specified in the lifecycle of an object is reached, OBS transitions the object as configured.

    • For buckets with versioning disabled, the Transition action changes the object storage class to Infrequent Access or Archive or Deep Archive.
    • For buckets with versioning enabled and suspended, the Transition action changes the storage class of the current object version to Infrequent Access or Archive or Deep Archive. This action does not affect the non-current versions of the object.
  • Action Expiration

    This action expires objects identified in the rule. Objects become unavailable once they expire. Whether the expired objects will be permanently deleted depends on the versioning status of the bucket.

    The Expiration action does not delete incomplete multipart uploads.

    • For buckets with versioning disabled, the Expiration action deletes objects permanently and the deleted objects cannot be restored.
    • For buckets with versioning enabled, this action applies only to current object versions, instead of non-current object versions. This action does not permanently delete current object versions. It retains the current version as a non-current version by adding a delete marker to it. This action will not be performed on current object versions that already have the delete markers. If the current object version is the only version of the object and has a delete marker, OBS will delete the current object version. Clearing a delete marker may take a while, because OBS needs to confirm that the delete marker is the only object version.

If you initiate a GET request on an object whose current version has the delete marker without specifying the version ID, OBS will identify the object as a deleted one and return error 404 Object Not Found. But you can specify the version ID in the GET request to recover the deleted object.

For example, you can set a rule to make the object named photo.gif expire 5 days after it is uploaded. If photo.gif is created at 10:30 UTC on January 1, 2016, the expiration rule will be executed at a time point after 00:00 UTC (five days after object creation) on January 7, 2016. The time will not be later than 23:59 UTC on January 7, 2016. For a bucket with versioning disabled, a deletion operation permanently deletes photo.gif. For a bucket with versioning enabled, after the expiration rule is executed, photo.gif (version 111111) is still stored in the bucket and can be accessed if needed, but the current version (version 4857693) of the object has a delete marker. The original object photo.gif turns to be a non-current version. For details about how a delete marker works, see Versioning.

For buckets with versioning suspended, OBS will create delete markers for expired objects whose version ID is null. Any existing null versions will be overwritten by new null versions, and data associated with this version cannot be restored.

Actions specific to buckets with versioning control enabled (or suspended)

The Transition and Expiration lifecycle actions can manage the lifecycle of current object versions. The NoncurrentVersionTransition and NonCurrentVersionExpiration actions can manage the lifecycle of noncurrent object versions.

The following lifecycle configuration actions can be performed only on buckets with versioning control enabled (or suspended). In a bucket with versioning control enabled, an object may have multiple versions, including a current version and zero or more non-current versions. You can use these actions to request OBS to perform specific operations on non-current object versions. These actions do not affect current object versions.

NoncurrentVersionTransition: Specifies the time period after which non-current versions will be transited from Standard to Infrequent Access or Archive.

NoncurrentVersionExpiration: Specifies the time period after which non-current object versions will be permanently deleted. The deleted objects cannot be recovered.

For example, if you want to enable a five-day period to correct any accidental deletion or overwriting, you can configure an expiration rule so that the object can be deleted 5 days after it has become a non-current version.

At 10:30 (UTC time) on January 1, 2016, you created object photo.gif with version ID 111111. At 10:30 (UTC time) on January 2, 2016, you accidentally deleted this object and OBS created a delete marker with version ID 4857693. In the next five days, you were allowed to recover the original object photo.gif with version ID 111111.

At 00:00 (UTC time) on January 8, 2016, 5 days after object photo.gif with version ID 111111 became non-current, the NoncurrentVersionExpiration action permanently deleted this object version.

How does OBS calculate how long an object has become non-current?

In a bucket with versioning enabled, an object can have multiple versions. There is always one current version and zero or more non-current versions. Each time an object is uploaded, the current version is saved as a non-current version, and the newly-uploaded version (the successor) becomes the current version. To determine the number of days an object version has become non-current, OBS checks when its successor was created. OBS uses the number of days since its successor was created as the number of days an object has been non-current.

Restoring a non-current version using the lifecycle configuration

You can use either of the following methods to restore an object to a non-current version:

  1. Copy a non-current object version of the object to the same bucket. The copied version will become the current version, and all object versions are reserved.
  2. Permanently delete the current version of the object. Deleting the current version of an object actually turns a non-current version into the current version.

You are advised to use the first method. Due to the consistency syntax of OBS, before the communication mode is changed, a current version that is permanently deleted may not disappear (OBS may be unaware of this deletion action). Meanwhile, the expiration action you configured for non-current versions may permanently delete non-current object versions, including those you want to restore. Therefore, copying a non-current version, as described in the first method, is more secure.

Table 1 lists the relationship between the lifecycle configuration rule and versioning status of a bucket.

Table 1 Lifecycle actions and bucket versioning status

Action

Bucket with Versioning Not Enabled

Bucket with Versioning Enabled

Bucket with Versioning Suspended

Transition

(Performed when a date or time period specified in the lifecycle rule is reached.)

Objects can be transitioned to Infrequent Access or Archive.

If the version is the current version and is not a delete marker, it can be transitioned to Infrequent Access or Archive.

Same action as a versioning-enabled bucket.

Expiration

(Performed when a date or time period specified in the lifecycle rule is reached.)

The Expiration action deletes the object, and the deleted object cannot be restored.

If the version is not a delete marker, this action inserts a delete marker that becomes the current version. The existing current version turns into a non-current version.

For buckets with versioning suspended, OBS will create delete markers for expired objects whose version ID is null. Any existing null versions will be overwritten by new null versions, and data associated with this version cannot be restored.

NoncurrentVersionTransition

(Performed when the object has become non-current for the specified number of days.)

The NoncurrentVersionTransition action has no effect.

If the version is not a delete marker or the current version, it can be transitioned to Infrequent Access or Archive.

Same action as a versioning-enabled bucket.

NoncurrentVersionExpiration

(Performed when the object has become non-current for the specified number of days.)

The NoncurrentVersionExpiration action has no effect.

The NoncurrentVersionExpiration action deletes the non-current version of the object, and the deleted object cannot be recovered.

Same action as a versioning-enabled bucket.

Date-based lifecycle rules

You can specify the execution dates for Transition and Expiration actions. The dates must conform to the ISO 8601 standards and the exact time is always 00:00 (UTC time). If you specify the time to a past date, all applicable objects will be executed immediately.

You cannot create date-based lifecycle rule on OBS Console.

A lifecycle action with a date specified is not a one-off action. Even if the date has passed, OBS will adopt this action as long as the lifecycle is enabled.

Assume you have specified a date for performing the Expiration action to delete all objects (without setting any filtering criteria). On the specified date, OBS makes all objects in the bucket expire. In addition, OBS continues to make all new objects created in the bucket expire. To terminate the Expiration action, you have to delete this action from your lifecycle configuration, disable the rule, or delete the rule from the lifecycle configuration.

Time period-based lifecycle rule

You can specify how many days after an object is created will the Transition or Expiration action will be performed on the object. After the number of days is specified, OBS starts to calculate the time from 00:00 (UTC time) on the next day. For example, you created an object at 2016-01-15 10:30 (UTC time) and you specified that objects would be changed 3 days after creation, the object would be transited at 2016-01-19 00:00 (UTC time).

OBS only records the last modification date for each object. On OBS Console, you can view the last modification time (LastModified) of an object on the object properties page. After an object is created, the date is the creation date. If the object is replaced, the date will also change.

When using the NoncurrentVersionTransition or NoncurrentVersionExpiration action, you can specify after how many days since an object changes to a non-current version (due to overwrite or deletion) will the action be performed on the object.

When you use the NoncurrentVersionTransition and NoncurrentVersionExpiration operations to specify the number of days, OBS adds the number of days specified in the rule to the time when the object version becomes a non-current version. Then the operation time is calculated starting from 00:00 (UTC time) of the next day. For example, the current version of an object in a bucket is created at 10:30 UTC on January 1, 2016. If the object version becomes a non-current version at 10:30 UTC on January 15, 2016 and you specify three days in the conversion rule, then the date for changing object storage class is calculated as 00:00 UTC on January 19, 2016.

When configuring the lifecycle rules, within a rule and for rules whose prefixes have inclusion relationship, Date or Days of Transition and Expiration must be consistent.

How to Use

You can use OBS Console, APIs, or SDKs to configure lifecycle rules.

Tool

Reference

OBS Console

Configuring a Lifecycle Rule

SDKs

OBS supports software development kits (SDKs) in multiple languages. For details, see the corresponding developer guide on the SDK Overview page.

API

Configuring Bucket Lifecycle Rules

Obtaining Bucket Lifecycle Configuration

Deleting Lifecycle Rules