Menu
Amazon Simple Storage Service
Developer Guide (API Version 2006-03-01)

Lifecycle Configuration Elements

You specify a lifecycle policy configuration as XML. It consists of one or more lifecycle rules. Each rule consists of the following:

  • Rule metadata that include a rule ID, and status indicating whether the rule is enabled or disabled. If a rule is disabled, Amazon S3 will not perform any actions specified in the rule.

  • Prefix identifying objects by the key prefix to which the rule applies.

  • One or more transition/expiration actions with a date or a time period in the object's lifetime when you want Amazon S3 to perform the specified action.

The following are two introductory example configurations.

Example 1. Lifecycle configuration

Suppose you want to transition objects with key prefix documents/ to the GLACIER storage class one year after you create them, and then permanently remove them 10 years after you created them. You can accomplish this by attaching the following lifecycle configuration to the bucket.

<LifecycleConfiguration>
    <Rule>
        <ID>sample-rule</ID>
        <Prefix>documents/</Prefix>
        <Status>Enabled</Status>
        <Transition>        
           <Days>365</Days>        
           <StorageClass>GLACIER</StorageClass>       
        </Transition>    
        <Expiration>
             <Days>3650</Days>
        </Expiration>
    </Rule>
</LifecycleConfiguration>

The lifecycle configuration defines one rule that applies to objects with the key name prefix documents/. The rule specifies two actions (Transition and Expiration). The rule is in effect because the rule status is Enabled.


Example 2. Lifecycle configuration on a versioning-enabled bucket

If your bucket is versioning-enabled, you have one current object version and zero or more noncurrent versions. For more information, see Object Versioning.

For a versioning-enabled bucket, the lifecycle actions apply as follows:

  • Transition and Expiration actions apply to current versions.

  • NoncurrentVersionTransition and NoncurrentVersionExpiration actions apply to noncurrent versions.

The following example lifecycle configuration has one rule that applies to objects with key name prefix logs/. The rule specifies two actions for noncurrent versions:

  • The NoncurrentVersionTransition action directs Amazon S3 to transition noncurrent objects to the GLACIER storage class 30 days after the objects become noncurrent.

  • The NoncurrentVersionExpiration action directs Amazon S3 to permanently remove the noncurrent objects 180 days after they become noncurrent.

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

The following sections describe these XML elements in a lifecycle configuration.

ID Element

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

Status Element

The Status element value can be either Enabled or Disabled. If a rule is disabled, Amazon S3 will not perform any of the actions defined in the rule.

Prefix Element

The Prefix element identifies objects to which the rule applies. If you specify an empty prefix, the rule applies to all objects in the bucket. If you specify a key name prefix, the rule applies only to the objects whose key name begins with specified string. For more information about object keys, see Object Keys.

Elements to Describe Lifecycle Actions

You can direct Amazon S3 to perform specific actions in an object's lifetime by specifying one or more of the following predefined actions in a lifecycle rule. The effect of these actions depend on the versioning state of your bucket.

  • Transition action element – You specify the Transition action to transition objects from one storage class to another. For more information about transitioning objects, see Supported Transitions. When a specified date or time period in the object's lifetime is reached, Amazon S3 performs the transition.

    For a versioned bucket (versioning-enabled or versioning-suspended bucket), the Transition action applies to the current object version. To manage noncurrent versions, Amazon S3 defines the NoncurrentVersionTranstion action (described below).

  • Expiration action element – The Expiration action expires objects identified in the rule. Amazon S3 makes all expired objects unavailable. Whether the objects are permanently removed depends on the versioning state of the bucket.

    Important

    Object expiration lifecycle polices do not remove incomplete multipart uploads. To remove incomplete multipart uploads you must use the AbortIncompleteMultipartUpload lifecycle configuration action that is described later in this section.

    • Non-versioned bucket – The Expiration action results in Amazon S3 permanently removing the object.

    • Versioned bucket – For a versioned bucket, versioning-enabled or versioning-suspended, (see Using Versioning), there are several considerations that guide how Amazon S3 handles the expiration action. Regardless of the version state, the following applies:

      • The expiration action applies only to the current version (no impact on noncurrent object versions).

      • Amazon S3 will not take any action if there are one or more object versions and the delete marker is the current version.

      • If the current object version is the only object version and it is also a delete marker (also referred as the "expired object delete marker", where all object versions are deleted and you only have a delete marker remaining), Amazon S3 will remove the expired object delete marker. You can also use the expiration action to direct Amazon S3 to remove any expired object delete markers. For an example, see Example 8: Removing Expired Object Delete Markers.

        Important

        Amazon S3 will remove an expired object delete marker no sooner than 48 hours after the object expired.

      The additional considerations for Amazon S3 to manage expiration are as follows:

      • Versioning-enabled bucket

        If current object version is not a delete marker, Amazon S3 adds a delete marker with a unique version ID, making the current version noncurrent, and the delete marker the current version.

      • Versioning-suspended bucket

        In a versioning-suspended bucket the expiration action causes Amazon S3 to create a delete marker with null as the version ID. This delete marker will replace any object version with a null version ID in the version hierarchy, which effectively deletes the object.

In addition, Amazon S3 provides the following actions that you can use to manage noncurrent object versions in a versioned bucket (versioning-enabled and versioning-suspended buckets).

  • NoncurrentVersionTransition action element – Use this action to specify how long (from the time the objects became noncurrent) you want the objects to remain in the current storage class before Amazon S3 transitions them to the specified storage class. For more information about transitioning objects, see Supported Transitions.

  • NoncurrentVersionExpiration action element – Use this action to specify how long (from the time the objects became noncurrent) you want to retain noncurrent object versions before Amazon S3 permanently removes them. The deleted object cannot be recovered.

    This delayed removal of noncurrent objects can be helpful when you need to correct any accidental deletes or overwrites. For example, you can configure an expiration rule to delete noncurrent versions five days after they become noncurrent. For example, suppose on 1/1/2014 10:30 AM UTC, you create an object called photo.gif (version ID 111111). On 1/2/2014 11:30 AM UTC, you accidentally delete photo.gif (version ID 111111), which creates a delete marker with a new version ID (such as version ID 4857693). You now have five days to recover the original version of photo.gif (version ID 111111) before the deletion is permanent. On 1/8/2014 00:00 UTC, the lifecycle rule for expiration executes and permanently deletes photo.gif (version ID 111111), five days after it became a noncurrent version.

    Important

    Object expiration lifecycle polices do not remove incomplete multipart uploads. To remove incomplete multipart uploads you must use the AbortIncompleteMultipartUpload lifecycle configuration action that is described later in this section.

In addition to the transition and expiration actions, you can use the following lifecycle configuration action to direct Amazon S3 to abort incomplete multipart uploads.

  • AbortIncompleteMultipartUpload action element – Use this element to set a maximum time (in days) that you want to allow multipart uploads to remain in progress. If the applicable multipart uploads (determined by the key name prefix specified in the lifecycle rule) are not successfully completed within the predefined time period, Amazon S3 will abort the incomplete multipart uploads. For more information, see Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle Policy.

How Amazon S3 Calculates How Long an Object Has Been Noncurrent

In a versioning-enabled bucket, you can have multiple versions of an object, there is always one current version, and zero or more noncurrent versions. Each time you upload an object, the current version is retained as noncurrent version and the newly added version, the successor, become current. To determine the number of days an object is noncurrent, Amazon S3 looks at when its successor was created. Amazon S3 uses the number of days since its successor was created as the number of days an object is noncurrent.

Restoring Previous Versions of an Object When Using Lifecycle Configurations

As explained in detail in the topic Restoring Previous Versions, there are two methods to retrieve previous versions of an object.

  1. By copying a noncurrent version of the object into the same bucket. The copied object becomes the current version of that object, and all object versions are preserved.

  2. By permanently deleting the current version of the object. When you delete the current object version, you, in effect, turn the noncurrent version into the current version of that object.

When using lifecycle configuration rules with versioning-enabled buckets, we recommend as a best practice that you use the first method.

Because of Amazon S3's eventual consistency semantics, a current version that you permanently deleted may not disappear until the changes propagate (Amazon S3 may be unaware of this deletion). And in the meantime, the lifecycle you configured to expire noncurrent objects may permanently remove noncurrent objects, including the one you want to restore. So, copying the old version, as recommended in the first method, is the safer alternative.

The following table summarizes the behavior of the lifecycle configuration rule actions on objects in relation to the versioning state of the bucket containing the object.

Lifecycle Actions and Bucket Versioning State

ActionNonversioned Bucket (Versioning Not Enabled)Versioning-Enabled BucketVersioning-Suspended Bucket

Transition

When a specified date or time period in the object's lifetime is reached.

Amazon S3 transitions the object to the specified storage class.Amazon S3 transitions the current version of the object to the specified storage class.Same behavior as a versioning-enabled bucket.

Expiration

When a specified date or time period in the object's lifetime is reached.

Expiration deletes the object, and the deleted object cannot be recovered.If the current version is not a delete marker, Amazon S3 creates a delete marker, which becomes the current version, and the existing current version is retained as a noncurrent version.The lifecycle creates a delete marker with null version ID, which becomes the current version. If the version ID of the current version of the object is null, the Expiration action permanently deletes this version. Otherwise, the current version is retained as a noncurrent version.

NoncurrentVersionTransition

When the specified number of days from the when the object becomes noncurrent is reached.

NoncurrentVersionTransition has no effect.

Amazon S3 transitions the noncurrent object versions to the specified storage class.

Same behavior as a versioning-enabled bucket.

NoncurrentVersionExpiration

When the specified number of days from the when the object becomes noncurrent is reached.

NoncurrentVersionExpiration has no effect.NoncurrentVersionExpiration action deletes the noncurrent version of the object, and the deleted object cannot be recovered.Same behavior as a versioning-enabled bucket.

Lifecycle Rules: Based on the Object Age

You can specify a time period in number of days from the creation (or modification) of the objects when Amazon S3 can take the action.

When you specify number of days in the Transition and Expiration actions in a lifecycle configuration, note the following:

  • It is the number of days since object creation when the action will be taken.

  • Amazon S3 calculates the time by adding the number of days specified in the rule to the object creation time and rounding the resulting time to the next day midnight UTC. For example, if an object was created at 1/15/2014 10:30 AM UTC and you specify 3 days in a transition rule, then the transition date of the object would be calculated as 1/19/2014 00:00 UTC.

Note

Amazon S3 maintains only the last modified date for each object. For example, the Amazon S3 console shows the Last Modified date in the object Properties pane. When you initially create a new object, this date reflects the date the object is created. If you replace the object, the date will change accordingly. So when we use the term creation date, it is synonymous with the term last modified date.

When specifying the number of days in the NoncurrentVersionTransition and NoncurrentVersionExpiration actions in a lifecycle configuration, note the following:

  • It is the number of days from when the version of the object becomes noncurrent (that is, since the object was overwritten or deleted), as the time period for when Amazon S3 will take the action on the specified object or objects.

  • Amazon S3 calculates the time by adding the number of days specified in the rule to the time when the new successor version of the object is created and rounding the resulting time to the next day midnight UTC. For example, in your bucket, you have a current version of an object that was created at 1/1/2014 10:30 AM UTC, if the new successor version of the object that replaces the current version is created at 1/15/2014 10:30 AM UTC and you specify 3 days in a transition rule, then the transition date of the object would be calculated as 1/19/2014 00:00 UTC.

Lifecycle Rules: Based on a Specific Date

When specifying an action in a lifecycle configuration, you can specify a date when you want Amazon S3 to take the action. The date-based rules trigger action on all objects created on or before this date. For example, a rule to transition to GLACIER on 6/30/2015 will transition all objects created on or before this date (note that the rule applies every day after the specified date and not just on the specified date as long as the rule is in effect).

Note

You cannot create the date-based rule using the AWS Management Console, but you can view, disable, or delete such rules.

Examples of Lifecycle Configuration

This section provides examples of lifecycle configuration. Each example shows how you can specify XML in each of the example scenarios.

Example 1: Specify a Lifecycle Rule for a Subset of Objects in a Bucket

The following lifecycle configuration rule is applied to a subset of objects with key name prefix projectdocs/. The rule specifies two actions requesting Amazon S3 the following:

  • Transition objects to the GLACIER storage class 365 days (one year) after creation.

  • Delete objects (the Expiration action) objects 3650 days (10 years) after creation.

<LifecycleConfiguration>
  <Rule>
    <ID>Transition and Expiration Rule</ID>
    <Prefix>projectdocs/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>365</Days>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
    <Expiration>
      <Days>3650</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

Instead of specifying object age in terms of days after creation, you can specify a date for each action; however, you cannot use both Date and Days in the same rule.

Example 2: Specify a Lifecycle Rule that Applies to All Objects in the Bucket

If you specify an empty Prefix in a lifecycle rule, it applies to all objects in the bucket. Suppose you create a bucket only for archiving objects to GLACIER. You can set lifecycle configuration requesting Amazon S3 to transition objects to the GLACIER storage class immediately after creation as shown.

The lifecycle configuration defines one rule with an empty Prefix. The rule specifies a Transition action requesting Amazon S3 to transition objects to the GLACIER storage class 0 days after creation in which case objects are eligible for archival to Amazon Glacier at midnight UTC following creation.

<LifecycleConfiguration>
  <Rule>
    <ID>Archive all object same-day upon creation</ID>
    <Prefix></Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>0</Days>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
  </Rule>
</LifecycleConfiguration>

Example 3: Disable a Lifecycle Rule

You can temporarily disable a lifecycle rule. The following lifecycle configuration specifies two rules; however, one of them is disabled. Amazon S3 will not perform any action specified in a rule that is disabled.

<LifecycleConfiguration>
  <Rule>
    <ID>30 days log objects expire rule</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>0</Days>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
  </Rule>
  <Rule>
    <ID>1 year documents expire rule</ID>
    <Prefix>documents/</Prefix>
    <Status>Disabled</Status>
    <Transition>
      <Days>0</Days>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
  </Rule>
</LifecycleConfiguration>

Example 4: Tiering Down Storage Class Over Object Lifetime

In this example, you leverage lifecycle configuration to tier-down the storage class of objects over their lifetime. This tiering down can help reduce storage costs. For more information about pricing, see Amazon S3 Pricing.

The following lifecycle configuration specifies a rule that applies to objects with key name prefix logs/. The rule specifies the following actions:

  • Two transition actions:

    • Transition objects to the STANDARD_IA storage class 30 days after creation.

    • Transition objects to the GLACIER storage class 90 days after creation.

  • An expiration action directing Amazon S3 to delete objects a year after creation.

<LifecycleConfiguration>
  <Rule>
    <ID>example-id</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>STANDARD_IA</StorageClass>
    </Transition>
    <Transition>
      <Days>90</Days>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
    <Expiration>
      <Days>365</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

Note

You can use one rule to describe all lifecycle actions if all actions apply to the same set of objects (identified by the prefix). Otherwise, you can add multiple rules each specify a different key name prefix.

Example 5: Specify Multiple Rules

You can specify multiple rules if you want different lifecycle actions of different objects. The following lifecycle configuration has two rules:

  • Rule 1 applies to objects with key name prefix classA/. It directs Amazon S3 to transition objects to the GLACIER storage class one year after creation and expire these objects 10 years after creation.

  • Rule 2 applies to objects with key name prefix classB/. It directs Amazon S3 to transition objects to the STANDARD_IA storage class 90 days after creation and delete then one year after creation.

<LifecycleConfiguration>
    <Rule>
        <ID>ClassADocRule</ID>
        <Prefix>classA/</Prefix>
        <Status>Enabled</Status>
        <Transition>        
           <Days>365</Days>        
           <StorageClass>GLACIER</StorageClass>       
        </Transition>    
        <Expiration>
             <Days>3650</Days>
        </Expiration>
    </Rule>
    <Rule>
        <ID>ClassBDocRule</ID>
        <Prefix>classB/</Prefix>
        <Status>Enabled</Status>
        <Transition>        
           <Days>90</Days>        
           <StorageClass>STANDARD_IA</StorageClass>       
        </Transition>    
        <Expiration>
             <Days>365</Days>
        </Expiration>
    </Rule>
</LifecycleConfiguration>

Example 6: Specify Multiple Rules with Overlapping Prefixes

In the following example you have two rules that specify overlapping prefixes.

  • First rule specifies empty prefix indicating all objects in the bucket.

  • Second rule specifies subset of objects in the bucket with key name prefix logs/.

These overlapping prefixes are fine, there is no conflict; Rule 1 requests Amazon S3 to delete all objects one year after creation, and Rule 2 requests Amazon S3 to transition subset of objects to the STANDARD_IA storage class 30 days after creation.

<LifecycleConfiguration>
  <Rule>
    <ID>Rule 1</ID>
    <Prefix></Prefix>
    <Status>Enabled</Status>
    <Expire>
      <Days>365</Days>
    </Expire>
  </Rule>
  <Rule>
    <ID>Rule 2</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <StorageClass>STANDARD_IA<StorageClass>
      <Days>30</Days>
    </Transition>
   </Rule>
</LifecycleConfiguration>

Example 7: Specify a Lifecycle Rule for a Versioning-Enable Bucket

Suppose you have a versioning-enabled bucket, which means that for each object you have a current version and zero or more noncurrent versions. You want to maintain one year worth of history and then delete the noncurrent versions. For more information about versioning, see Object Versioning.

Also you want to save storage costs by moving noncurrent versions to GLACIER 30 days after they become noncurrent (assuming cold data for which you will not need real-time access). In addition, you also expect frequency of access of the current versions to diminish 90 days after creation so you might choose to move these objects to the STANDARD_IA storage class.

<LifecycleConfiguration>
    <Rule>
        <ID>sample-rule</ID>
        <Prefix></Prefix>
        <Status>Enabled</Status>
        <Transition>
           <Days>90</Days>
           <StorageClass>STANDARD_IA</StorageClass>
        </Transition>
        <NoncurrentVersionTransition>      
            <NoncurrentDays>30</NoncurrentDays>      
            <StorageClass>GLACIER</StorageClass>   
        </NoncurrentVersionTransition>    
       <NoncurrentVersionExpiration>     
            <NoncurrentDays>365</NoncurrentDays>    
       </NoncurrentVersionExpiration> 
    </Rule>
</LifecycleConfiguration>

Example 8: Removing Expired Object Delete Markers

A versioning-enabled bucket has one current version and one or more noncurrent versions for each object. When you delete an object, note that

  • If you don't specify a version ID in your delete request, Amazon S3 adds a delete marker instead of deleting the object. The current object version become noncurrent, and the delete marker becomes the current version.

  • If you specify a version ID in your delete request, Amazon S3 deletes the object version permanently (a delete marker is not created).

  • A delete marker with zero noncurrent versions is referred to as the expired object delete marker.

This example shows a scenario that can create expired object delete markers in your bucket and how you can use lifecycle configuration to direct Amazon S3 to remove the expired object delete markers.

Suppose you write a lifecycle policy that specifies the NoncurrentVersionExpiration action to remove the noncurrent versions 30 days after they become noncurrent as shown:

<LifecycleConfiguration>
    <Rule>
        ...
        <NoncurrentVersionExpiration>     
            <NoncurrentDays>30</NoncurrentDays>    
        </NoncurrentVersionExpiration>
    </Rule>
</LifecycleConfiguration>

Note that the NoncurrentVersionExpiration action does not apply to the current object versions, it only removes noncurrent versions.

For current object versions, you have the following options to manage their lifetime depending on whether or not the current object versions follow a well-defined lifecycle:

  • Current object versions follow a well-defined lifecycle.

    In this case you can use lifecycle policy with the Expiration action to direct Amazon S3 to remove current versions as shown in the following example:

    <LifecycleConfiguration>
        <Rule>
            ...
            <Expiration>
               <Days>60</Days>
            </Expiration>
            <NoncurrentVersionExpiration>     
                <NoncurrentDays>30</NoncurrentDays>    
            </NoncurrentVersionExpiration>
        </Rule>
    </LifecycleConfiguration>

    Amazon S3 removes current versions 60 days after they are created by adding a delete marker for each of the current object versions. This makes the current version noncurrent and the delete marker becomes the current version (see Using Versioning).

    The NoncurrentVersionExpiration action in the same lifecycle configuration removes noncurrent objects 30 days after they become noncurrent. Thus all object versions are removed and you have expired object delete markers, but Amazon S3 will detect and remove expired object delete markers for you.

  • Current object versions don't have a well-defined lifecycle.

    In this case you might remove the objects manually when you don't need them, creating a delete marker with one or more noncurrent versions. If lifecycle configuration with NoncurrentVersionExpiration action removes all the noncurrent versions, you now have expired object delete markers.

    Specifically for this scenario, Amazon S3 lifecycle configuration provides Expiration action where you can request S3 to remove the expired object delete markers:

    <LifecycleConfiguration>
        <Rule>
            ...
            <Expiration>
               <ExpiredObjectDeleteMarker>true</ExpiredObjectDeleteMarker>
            </Expiration>
            <NoncurrentVersionExpiration>     
                <NoncurrentDays>30</NoncurrentDays>    
            </NoncurrentVersionExpiration>
        </Rule>
    </LifecycleConfiguration>

By setting the ExpiredObjectDeleteMarker element to true in the Expiration action, you direct Amazon S3 to remove expired object delete markers. Amazon S3 will remove an expired object delete marker no sooner than 48 hours after the object expired.

The following put-bucket-lifecycle  CLI command adds the lifecycle configuration for the specified bucket.

$ aws s3api put-bucket-lifecycle  \
--bucket bucketname  \
--lifecycle-configuration filename-containing-lifecycle-configuration 

Note

If you have trouble getting the following test procedure to work, make sure that you have the latest version of the AWS CLI installed.

To test the CLI command, do the following:

  1. Set up the AWS CLI. For instructions, see Set Up the AWS CLI.

  2. Save the following example lifecycle configuration in a file (lifecycle.json). The example policy specifies empty prefix so it applies to all objects. You could specify a key name prefix to limit action to a subset of objects.

    {
        "Rules": [
            {
                "Status": "Enabled",
                "Prefix": "",
                "Expiration": {
                    "ExpiredObjectDeleteMarker": true
                },
                "ID": "TestOnly"
            }
        ]
    }

  3. Run the following CLI command to set lifecycle configuration on your bucket.

    $ aws s3api put-bucket-lifecycle  \
    --bucket bucketname  \
    --lifecycle-configuration file://lifecycle.json 
  4. To verify, retrieve the lifecycle configuration using the get-bucket-lifecycle CLI command.

    $ aws s3api get-bucket-lifecycle  \
    --bucket bucketname  

  5. To delete the lifecycle configuration use the delete-bucket-lifecycle CLI command.

    aws s3api delete-bucket-lifecycle \
    --bucket bucketname