Amazon Simple Storage Service
API Reference (API Version 2006-03-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

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.

To use this operation, you must be allowed to perform the s3:PutLifecycleConfiguration action. By default, the bucket owner has this permission and can grant this permission to others.

Note

If your bucket is version-enabled or versioning is suspended, you cannot add a lifecycle configuration.

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 and

s3:PutLifecycleConfiguration

For more information, go to Access Control section in the Amazon Simple Storage Service Developer Guide .

If you want to block users or accounts from managing lifecycle configurations, you must deny permission for the s3:PutLifecycleConfiguration action.

Requests

Syntax

PUT /?lifecycle HTTP/1.1
Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4))
Content-MD5: MD5

Lifecycle configuration in the request body

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 with the following elements.

Name Description Required
Date

Indicates when the specific rule take effect.

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 is absent
Days

Indicates the number of days after creation when the specific rule take effect.

Type: non-negative integer

Ancestor: Expiration or Transition

Yes, if Date is absent
Expiration

Container for the object expiration rule.

Type: Container

Children: Days or Date

Ancestor: Rule

Yes, if Transition is absent in a 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
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.

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
Transition

Container for the transition rule that describes when objects transition to the Glacier storage class.

Type: Container

Ancestor: Rule

Yes, if Expiration is absent in the Rule
StorageClass

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

Type: String

Ancestor: Transition

Valid values: GLACIER.

Yes

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: Configure lifecycle - Archive objects immediately

The following lifecycle configuration rule sets objects with key prefix "glacierobjects/" to transition to storage class "GLACIER" soon after creation. Note the transition days value is zero.

<LifecycleConfiguration>
  <Rule>
    <ID>archive-objects-glacier-immediately-upon-creation</ID>
    <Prefix>glacierobjects/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>0</Days>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
  </Rule>
</LifecycleConfiguration>

When you upload an object with "glacierobjects/" key prefix, Amazon S3 archives the object by the next day midnight UTC and sets its storage class to Glacier.

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: Tue, 16 Oct 2012 04:20:50 GMT
Content-MD5: 8dYiLewFWZyGgV2Q5FNI4W==
Authorization: authorization string
Content-Length: 294

<LifecycleConfiguration>
  <Rule>
    <ID>Transition-Immediately-Rule</ID>
    <Prefix>glacierobjects/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>0</Days>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
  </Rule>
</LifecycleConfiguration>

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: cIC06kjwLCeh41RP7SVdOtPOBYRJdvCqFGf/GYCL4nXgpMqZaFlmrugH6/CFX2Zf4fCeCURX1s0=
x-amz-request-id: D92FE35006B77B4A
Date: Tue, 16 Oct 2012 04:20:37 GMT
Content-Length: 0
Server: AmazonS3

Example 2: Configure lifecycle - First archive and later expire objects

The following PUT /?lifecycle request adds a lifecycle configuration to the examplebucket bucket. The lifecycle configuration requests Amazon S3 to transition the objects with prefix glacierobjects/ to the storage class Glacier on December 31, 2012, and subsequently expire them 10 years later.

PUT /?lifecycle HTTP/1.1
Host: examplebucket.s3.amazonaws.com 
x-amz-date: Wed, 17 Oct 2012 04:11:08 GMT
Content-MD5: 8dYiLewFWZyGgV2Q5FNI4W==
Authorization: authorization string
Content-Length: 399

<LifecycleConfiguration>
  <Rule>
    <ID>first-archive-then-expire</ID>
    <Prefix>glacierobjects/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Date>2012-12-31T00:00:00.000Z</Date>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
    <Expiration>
      <Date>2022-10-12T00:00:00.000Z</Date>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

The preceding configuration uses date in the setting rules. You can optionally specify number of days since the creation of the objects when these rules take effect as shown in the following example. The lifecycle configuration requests Amazon S3 transition objects with key prefix "glacierobjects/" to Glacier storage class (archive them) 30 days after creation and delete them 365 days after creation date.

PUT /?lifecycle HTTP/1.1
Host: examplebucket.s3.amazonaws.com 
x-amz-date: Wed, 17 Oct 2012 04:11:08 GMT
Content-MD5: 8dYiLewFWZyGgV2Q5FNI4W==
Authorization: authorization string
Content-Length: 399

<LifecycleConfiguration>
  <Rule>
    <ID>first-archive-then-expire</ID>
    <Prefix>glacierobjects/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>GLACIER</StorageClass>
    </Transition>
    <Expiration>
      <Days>365</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

Example 3: Configure lifecycle - Specify rule that applies to all objects in the bucket

When you specify an empty prefix, the rule applies to all objects in the bucket. The following PUT /?lifecycle request adds a lifecycle configuration to expire all objects in the bucket 10 years after creation. Note the empty Prefix in the configuration.

PUT /?lifecycle HTTP/1.1
Host: examplebucket.s3.amazonaws.com 
x-amz-date: Tue, 13 Dec 2011 17:54:50 GMT
Content-MD5: 8dYiLewFWZyGgV2Q5FNI4W==
Authorization: authorization string
Content-Length: 226

<LifecycleConfiguration>
  <Rule>
    <ID>delete-all-10-years-after-creation</ID>
    <Prefix></Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>3650</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>