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

PUT Bucket lifecycle

Description

Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration. For information about lifecycle configuration, go to Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.

Permissions

By default, all Amazon S3 resources are private, including buckets, objects, and related subresources (for example, lifecycle configuration and website configuration). Only the resource owner (that is, the AWS account that created it) can access the resource. The resource owner can optionally grant access permissions to others by writing an access policy. For this operation, a user must get the s3:PutLifecycleConfiguration permission.

You can also explicitly deny permissions. Explicit deny also supersedes any other permissions. If you want to block users or accounts from removing or deleting objects from your bucket, you must deny them permissions for the following actions.

  • s3:DeleteObject

  • s3:DeleteObjectVersion

  • s3:PutLifecycleConfiguration

For more information about permissions, see Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

PUT /?lifecycle HTTP/1.1
Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string 
Content-MD5: MD5

Lifecycle configuration in the request body

For details about authorization string, see Authenticating Requests (AWS Signature Version 4).

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required
Content-MD5

The base64-encoded 128-bit MD5 digest of the data. This header must be used as a message integrity check to verify that the request body was not corrupted in transit. For more information, go to RFC 1864.

Type: String

Default: None

Yes

Request Body

In the request, you specify lifecycle configuration in the request body. The lifecycle configuration is specified as XML. The following is an introductory example lifecycle configuration skeleton. It specifies one rule. The Prefix in the rule identifies objects to which the rule applies. The rule also specifies two actions (Transitionand Expiration). Each action specifies a timeline when you want Amazon S3 to perform the action. The Status indicates whether the rule is enabled or disabled.

<LifecycleConfiguration>
    <Rule>
        <ID>sample-rule</ID>
        <Prefix>key-prefix</Prefix>
        <Status>rule-status</Status>
        <Transition>        
           <Date>value</Date>        
           <StorageClass>storage class</StorageClass>       
        </Transition>    
        <Expiration>
           <Days>value</Days>
        </Expiration>
    </Rule>
</LifecycleConfiguration>

If the state of your bucket is versioning-enabled or versioning-suspended, you can have many versions of the same object, one current version, and zero or more noncurrent versions. The following lifecycle configuration specifies the actions (NoncurrentVersionTransition, NoncurrentVersionExpiration) that are specific to noncurrent object versions.

<LifecycleConfiguration>
    <Rule>
        <ID>sample-rule</ID>
        <Prefix>key-prefix</Prefix>
        <Status>rule-status</Status>
        <NoncurrentVersionTransition>      
           <NoncurrentDays>value</NoncurrentDays>      
           <StorageClass>storage class</StorageClass>   
        </NoncurrentVersionTransition>    
        <NoncurrentVersionExpiration>     
           <NoncurrentDays>value</NoncurrentDays>    
        </NoncurrentVersionExpiration> 
    </Rule>
</LifecycleConfiguration>

You can use the multipart upload API to upload large objects in parts. For more information about multipart uploads, see Multipart Upload Overview in the Amazon Simple Storage Service Developer Guide. Using lifecycle configuration, you can direct Amazon S3 to abort incomplete multipart uploads (identified by the key name prefix specified in the rule) if they don't complete within a specified number of days after initiation. When Amazon S3 aborts a multipart upload, it deletes all parts associated with the multipart upload. This ensures that you don't have incomplete multipart uploads with parts that are stored in Amazon S3 and, therefore, you don't have to pay any storage costs for these parts. The following is an example lifecycle configuration that specifies a rule with the AbortIncompleteMultipartUpload action. This action requests Amazon S3 to abort incomplete multipart uploads seven days after initiation.

<LifecycleConfiguration>
    <Rule>
        <ID>sample-rule</ID>
        <Prefix>SomeKeyPrefix/</Prefix>
        <Status>rule-status</Status>
        <AbortIncompleteMultipartUpload>
          <DaysAfterInitiation>7</DaysAfterInitiation>
        </AbortIncompleteMultipartUpload>
    </Rule>
</LifecycleConfiguration>

The following table describes the XML elements in the lifecycle configuration:

Name Description Required
AbortIncompleteMultipartUpload

Container for specifying when an incomplete multipart upload becomes eligible for an abort operation.

Child: DaysAfterInitiation

Type: Container

Ancestor: Rule.

Yes, if no other action is specified for the rule.
Date

Specifies the date after which you want the corresponding action to take effect. When the action is in effect, Amazon S3 performs the specific action on the applicable objects as they appear in the bucket (you identify applicable objects in the lifecycle Rule in which the action is defined).

For example, suppose you add a Transition action to take effect on December 31, 2014. Suppose this action applies to objects with key prefix documents/. When the action takes effect on this date, Amazon S3 transitions existing applicable objects to the GLACIER storage class. As long as the action is in effects, Amazon S3 transitions any new objects, even after December 31, 2014.

The date value must conform to the ISO 8601 format. The time is always midnight UTC.

Type: String

Ancestor: Expiration or Transition

Yes, if Days and ExpiredObjectDeleteMarker are absent.
Days

Specifies the number of days after object creation when the specific rule action takes effect.

Type: Nonnegative Integer when used with Transition, Positive Integer when used with Expiration.

Ancestor: Expiration, Transition.

Yes, if Date and ExpiredObjectDeleteMarker are absent.
DaysAfterInitiation

Specifies the number of days after initiating a multipart upload when the multipart upload must be completed. If it does not complete by the specified number of days, it becomes eligible for an abort operation and Amazon S3 aborts the incomplete multipart upload.

Type: Positive Integer.

Ancestor: AbortIncompleteMultipartUpload.

Yes, if parent tag is specified.
Expiration

This action specifies a period in an object's lifetime when Amazon S3 should take the appropriate expiration action. The action Amazon S3 takes depends on whether the bucket is versioning-enabled.

  • If versioning has never been enabled on the bucket, Amazon S3 deletes the only copy of the object permanently.

  • Otherwise, if your bucket is versioning-enabled (or versioning is suspended), the action applies only to the current version of the object. A versioning-enabled bucket can have many versions of the same object, one current version, and zero or more noncurrent versions.

    Instead of deleting the current version, Amazon S3 makes it a noncurrent version by adding a delete marker as the new current version.

    Important

    If your bucket state is versioning-suspended, Amazon S3 creates a delete marker with version ID null. If you have a version with version ID null, then Amazon S3 overwrites that version.

    Note

    To set expiration for noncurrent objects, you must use the NoncurrentVersionExpiration action.

Type: Container

Children: Days or Date

Ancestor: Rule

Yes, if no other action is present in the Rule.
ID

Unique identifier for the rule. The value cannot be longer than 255 characters.

Type: String

Ancestor: Rule

No
LifecycleConfiguration

Container for lifecycle rules. You can add as many as 1000 rules.

Type: Container

Children: Rule

Ancestor: None

Yes
ExpiredObjectDeleteMarker

On a versioned bucket (versioning-enabled or versioning-suspended bucket), you can add this element in the lifecycle configuration to direct Amazon S3 to delete expired object delete markers. For an example, go to Example 8: Removing Expired Object Delete Markers in the Amazon Simple Storage Service Developer Guide. On a non-versioned bucket, adding this element in a policy is meaningless because you cannot have delete markers and the element will not do anything.

Type: String

Valid values: true | false (the value false is allowed, but it is no-op and Amazon S3 will not take action if the value is false)

Ancestor: Expiration.

Yes, if Date and Days are absent.
NoncurrentDays

Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.

Type: Nonnegative Integer when used with NoncurrentVersionTransition, Positive Integer when used with NoncurrentVersionExpiration.

Ancestor: NoncurrentVersionExpiration or NoncurrentVersionTransition

Yes
NoncurrentVersionExpiration

Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes the noncurrent object versions.

You set this lifecycle configuration action on a bucket that has versioning enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a specific period in the object's lifetime.

Type: Container

Children: NoncurrentDays

Ancestor: Rule

Yes, if no other action is present in the Rule.
NoncurrentVersionTransition

Container for the transition rule that describes when noncurrent objects transition to the STANDARD_IA or GLACIER storage class.

If your bucket is versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3 transition noncurrent object versions at a specific period in the object's lifetime.

Type: Container

Children: NoncurrentDays and StorageClass

Ancestor: Rule

Yes, if no other action is present in the Rule.
Prefix

Object key prefix identifying one or more objects to which the rule applies.

Type: String

Ancestor: Rule

Yes
Rule

Container for a lifecycle rule. A lifecycle configuration can contain as many as 1000 rules.

Type: Container

Ancestor:LifecycleConfiguration

Yes
Status

If Enabled, Amazon S3 executes the rule as scheduled. If Disabled, Amazon S3 ignores the rule.

Type: String

Ancestor: Rule

Valid values: Enabled, Disabled.

Yes
StorageClass

Specifies the Amazon S3 storage class to which you want the object to transition.

Type: String

Ancestor: Transition and NoncurrentVersionTransition

Valid values: STANDARD_IA | GLACIER.

Yes

This element is required only if you specify one or both its ancestors.

Transition

This action specifies a period in the objects' lifetime when Amazon S3 should transition them to the STANDARD_IA or the GLACIER storage class. When this action is in effect, what Amazon S3 does depends on whether the bucket is versioning-enabled.

  • If versioning has never been enabled on the bucket, Amazon S3 transitions the only copy of the object to the specified storage class.

  • Otherwise, when your bucket is versioning-enabled (or versioning is suspended) Amazon S3 transitions only the current versions of objects identified in the rule.

    Note

    A versioning-enabled bucket can have many versions of an object. This action has no impact on the noncurrent object versions. To transition noncurrent objects, you must use the NoncurrentVersionTransition action.

Type: Container

Children: Days or Date, and StorageClass

Ancestor: Rule

Yes, if no other action is present in the Rule.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Example 1: Add lifecycle configuration - bucket not versioning-enabled

The following lifecycle configuration specifies two rules, each with one action.

  • The Transition action requests Amazon S3 to transition objects with the "documents/" prefix to the GLACIER storage class 30 days after creation.

  • The Expiration action requests Amazon S3 to delete objects with the "logs/" prefix 365 days after creation.


<LifecycleConfiguration>
  <Rule>
    <ID>id1</ID>
    <Prefix>documents/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
  </Rule>
  <Rule>
    <ID>id2</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>365</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

The following is a sample PUT /?lifecycle request that adds the preceding lifecycle configuration to the examplebucket bucket.

PUT /?lifecycle HTTP/1.1
Host: examplebucket.s3.amazonaws.com 
x-amz-date: Wed, 14 May 2014 02:11:21 GMT
Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Authorization: authorization string
Content-Length: 415

<LifecycleConfiguration>
  <Rule>
    <ID>id1</ID>
    <Prefix>documents/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
  </Rule>
  <Rule>
    <ID>id2</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>365</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc
x-amz-request-id: 9E26D08072A8EF9E
Date: Wed, 14 May 2014 02:11:22 GMT
Content-Length: 0
Server: AmazonS3

Example 2: Add lifecycle configuration - bucket is versioning-enabled

The following lifecycle configuration specifies two rules, each with one action for Amazon S3 to perform. You specify these actions when your bucket is versioning-enabled or versioning is suspended:

  • The NoncurrentVersionExpiration action requests Amazon S3 to expire noncurrent versions of objects with the "logs/" prefix 100 days after the objects become noncurrent.

  • The NoncurrentVersionTransition action requests Amazon S3 to transition noncurrent versions of objects with the "documents/" prefix to the GLACIER storage class 30 days after they become noncurrent.

<LifeCycleConfiguration>
  <Rule>
    <ID>DeleteAfterBecomingNonCurrent</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <NoncurrentVersionExpiration>
      <NoncurrentDays>100</NoncurrentDays>
    </NoncurrentVersionExpiration>
  </Rule>
  <Rule>
    <ID>TransitionAfterBecomingNonCurrent</ID>
    <Prefix>documents/</Prefix>
    <Status>Enabled</Status>
    <NoncurrentVersionTransition>
      <NoncurrentDays>30</NoncurrentDays>
      <StorageClass>GLACIER</StorageClass>
    </NoncurrentVersionTransition>
  </Rule>
</LifeCycleConfiguration>

The following is a sample PUT /?lifecycle request that adds the preceding lifecycle configuration to the examplebucket bucket.

PUT /?lifecycle HTTP/1.1
Host: examplebucket.s3.amazonaws.com 
x-amz-date: Wed, 14 May 2014 02:21:48 GMT
Content-MD5: 96rxH9mDqVNKkaZDddgnw==
Authorization: authorization string
Content-Length: 598

<LifeCycleConfiguration>
  <Rule>
    <ID>DeleteAfterBecomingNonCurrent</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <NoncurrentVersionExpiration>
      <NoncurrentDays>1</NoncurrentDays>
    </NoncurrentVersionExpiration>
  </Rule>
  <Rule>
    <ID>TransitionSoonAfterBecomingNonCurrent</ID>
    <Prefix>documents/</Prefix>
    <Status>Enabled</Status>
    <NoncurrentVersionTransition>
      <NoncurrentDays>0</NoncurrentDays>
      <StorageClass>GLACIER</StorageClass>
    </NoncurrentVersionTransition>
  </Rule>
</LifeCycleConfiguration>

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: aXQ+KbIrmMmoO//3bMdDTw/CnjArwje+J49Hf+j44yRb/VmbIkgIO5A+PT98Cp/6k07hf+LD2mY=
x-amz-request-id: 02D7EC4C10381EB1
Date: Wed, 14 May 2014 02:21:50 GMT
Content-Length: 0
Server: AmazonS3

Additional Examples

Lifecycle configuration topic in the developer guide provides additional examples of transitioning objects to storage classes such as STANDARD_IA. For more information, go to Examples of Lifecycle Configuration.