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.
Note
Bucket lifecycle configuration now supports specifying a lifecycle rule using an object key name prefix, one or more object tags, or a combination of both. Accordingly, this section describes the latest API. The previous version of the API supported filtering based only on an object key name prefix, which is supported for backward compatibility. For the related API description, see PUT Bucket lifecycle (Deprecated).
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, see RFC 1864. Type: String Default: None |
Yes |
Request Body
You specify the lifecycle configuration in your request body. The lifecycle configuration is specified as XML consisting of one or more rules.
<LifecycleConfiguration> <Rule> ... </Rule> <Rule> ... </Rule> … </LifecycleConfiguration>
Each rule consists of the following:
-
Filter identifying a subset of objects to which the rule applies. The filter can be based on a key name prefix, object tags, or a combination of both.
-
Status whether the rule is in effect.
-
One or more lifecycle transition and expiration actions that you want Amazon S3 to perform on the objects identified by the filter. 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). Amazon S3 provides predefined actions that you can specify for current and noncurrent object versions.
For example,
<LifecycleConfiguration> <Rule> <Filter> <Prefix>
key-prefix
</Prefix> </Filter> <Status>rule-status
</Status>One or more Transition/Expiration lifecycle actions.
</Rule> </LifecycleConfiguration>
For more information, see Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.
For more information, see Lifecycle Configuration Elements in the Amazon Simple Storage Service Developer Guide.
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. When you specify this lifecycle action, the rule cannot specify a tag-based filter. For more information, see Lifecycle Configuration Elements in the Amazon Simple Storage Service Developer Guide. Child: Type: Container Ancestor: |
Yes, if no other action is specified for the rule. |
And
|
Container for specify rule filters. These filters determine the subset of objects to which the rule applies. Type: String Ancestor: |
Yes, if you specify more than one filter condition (for example, one prefix and one or more tags). |
Date
|
Date when you want Amazon S3 to take the action. For more information, see Lifecycle Rules: Based on a Specific Date in the Amazon Simple Storage Service Developer Guide. The date value must conform to the ISO 8601 format. The time is always midnight UTC. Type: String Ancestor: |
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
Ancestor: |
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: |
Yes, if ancestor 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.
Type: Container Children: Days or Date Ancestor: |
Yes, if no other action is present in the
Rule .
|
Filter
|
Container for elements that describe the filter identifying a
subset of objects to which the lifecycle rule applies. If you
specify an empty filter
( Type: String Children: Prefix, Tag Ancestor: |
Yes |
ID
|
Unique identifier for the rule. The value cannot be longer than 255 characters. Type: String Ancestor: |
No |
Key |
Specifies the key of a tag. A tag key can be up to 128 Unicode characters in length. Tag keys that you specify in a lifecycle rule filter must be unique. For more information, see Object Tagging in the Amazon Simple Storage Service Developer Guide. Type: String Ancestor: |
Yes, if <Tag> parent is specified. |
LifecycleConfiguration |
Container for lifecycle rules. You can add as many as 1,000 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, see Example 7: Removing Expired Object Delete Markers in the Amazon Simple Storage Service Developer Guide. On a nonversioned bucket, adding this element in a policy is meaningless because you cannot have delete markers and the element doesn't do anything. For more information, see Lifecycle Configuration Elements in the Amazon Simple Storage Service Developer Guide. When you specify this lifecycle action, the rule cannot specify a tag-based filter. Type: String Valid values: Ancestor: |
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
Ancestor: |
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: Ancestor: |
Yes, if no other action is present in the
Rule .
|
NoncurrentVersionTransition |
Container for the transition rule that describes when noncurrent objects transition
to
the
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: Ancestor: |
Yes, if no other action is present in the
Rule .
|
Prefix
|
Object key prefix identifying one or more objects to which the
rule applies. Empty prefix
( There can be at most one Type: String Ancestor: |
No |
Rule
|
Container for a lifecycle rule. A lifecycle configuration can contain as many as 1,000 rules. Type: Container Ancestor: |
Yes |
Status
|
If Enabled, Amazon S3 executes the rule as scheduled. If Disabled, Amazon S3 ignores the rule. Type: String Ancestor: Valid values: |
Yes |
StorageClass
|
Specifies the Amazon S3 storage class to which you want the object to transition. Type: String Ancestor: Valid values: STANDARD_IA |
|
Yes This element is required only if you specify one or both its ancestors. |
Tag
|
Container for specifying a tag key and value. Each tag has a key and a value. Type: Container Children: Key and Value Ancestor: |
No |
Transition
|
This action specifies a period in the objects' lifetime when Amazon S3 should transition
them to the
Type: Container Children: Ancestor: |
Yes, if no other action is present in the
Rule .
|
Value
|
Specifies the value for a tag key. Each object tag is a key-value pair. Tag value can be up to 256 Unicode characters in length. Type: String Ancestor: |
Yes, if <Tag> parent is specified. |
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> <Filter> <Prefix>documents/</Prefix> </Filter> <Status>Enabled</Status> <Transition> <Days>30</Days> <StorageClass>GLACIER</StorageClass> </Transition> </Rule> <Rule> <ID>id2</ID> <Filter> <Prefix>logs/</Prefix> </Filter> <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> <Filter> <Prefix>documents/</Prefix> </Filter> <Status>Enabled</Status> <Transition> <Days>30</Days> <StorageClass>GLACIER</StorageClass> </Transition> </Rule> <Rule> <ID>id2</ID> <Filter> <Prefix>logs/</Prefix> </Filter> <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> <Filter> <Prefix>logs/</Prefix> </Filter> <Status>Enabled</Status> <NoncurrentVersionExpiration> <NoncurrentDays>100</NoncurrentDays> </NoncurrentVersionExpiration> </Rule> <Rule> <ID>TransitionAfterBecomingNonCurrent</ID> <Filter> <Prefix>documents/</Prefix> </Filter> <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> <Filter> <Prefix>logs/</Prefix> </Filter> <Status>Enabled</Status> <NoncurrentVersionExpiration> <NoncurrentDays>1</NoncurrentDays> </NoncurrentVersionExpiration> </Rule> <Rule> <ID>TransitionSoonAfterBecomingNonCurrent</ID> <Filter> <Prefix>documents/</Prefix> </Filter> <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. For more information, go to Examples of Lifecycle Configuration.