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

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

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: `DaysAfterInitiation` Type: Container Ancestor: `Rule`.	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: `Rule`	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: `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 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. 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`.
`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 (`<Filter></Filter>`), the rule applies to all objects in the bucket. Type: String Children: Prefix, Tag Ancestor: `Rule`	Yes
`ID`	Unique identifier for the rule. The value cannot be longer than 255 characters. Type: String Ancestor: `Rule`	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: `Tag`	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: `true` \| `false` (the value `false` is allowed, but it is no-op and Amazon S3 does 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`, `ONEZONE_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. Empty prefix (`<Prefix></Prefix>`) indicates there is no filter based on key prefix. There can be at most one `Prefix` in a lifecycle rule `Filter`. Type: String Ancestor: `Filter` or `And` (if you specify multiple filters such as a prefix and one or more tags).	No
`Rule`	Container for a lifecycle rule. A lifecycle configuration can contain as many as 1,000 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 \| `ONEZONE_IA` \| GLACIER.	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: `Filter` or `And` (if you specify multiple filters such as a prefix and one or more tags).	No
`Transition`	This action specifies a period in the objects' lifetime when Amazon S3 should transition them to the `STANDARD_IA`, `ONEZONE_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`.
`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: `Tag`	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>