PUT Bucket Lifecycle

The PUT Bucket Lifecycle operation creates a new lifecycle configuration or replaces an existing one.

Requests

Request Syntax

PUT /?lifecycle HTTP/1.1
Host: {{BucketName}}.{{StorageService}}.com
Content-Length: {{length}}
Date: {{date}}
Authorization: {{authorizationString}}
Content-MD5: MD5

Request Parameters

The PUT Bucket Lifecycle operation does not use request parameters.

Request Headers

Name Type Required
Content MD-5

The base64-encoded 128-bit MD5 digest of the data; 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

The lifecycle configuration can be specified in the request body. The configuration is specified as XML consisting of one or more rules.

<LifecycleConfiguration>
  <Rule>
    ...
  </Rule>
  <Rule>
    ...
  </Rule>
</LifecycleConfiguration>

Each rule consists of the following:

  • A 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.
  • A status, indicating whether the rule is in effect.
  • One or more lifecycle transition and expiration actions 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 non-current versions). Amazon S3 provides predefined actions that you can specify for current and non-current 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>

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

Name Type 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.

Type: Container

Child: DaysAfterInitiation

Ancestor: Rule

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

Container for specifying rule filters. These filters determine the subset of objects to which the rule applies.

Type: String

Ancestor: Rule

Yes, if more than one filter condition is specified (for example, one prefix and one or more tags).
Date

Date when action should occur. The date value must conform to the ISO 8601 format.

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 or 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: AbortIncompleteMultip artUpload

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. Action taken depends on whether the bucket is versioning-enabled.

If versioning has never been enabled on the bucket, the only copy of the object is deleted permanently.

Otherwise, if your bucket is versioning-enabled or versioning-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, the current version becomes a noncurrent version and a delete marker is added as the new current version.

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, the rule applies to all objects in the bucket.

Type: String

Children: Prefix or 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.

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 versioning-enabled or versioning-suspended bucket, you can add this element in the lifecycle configuration to delete expired object delete markers.

On a non-versioned bucket, adding this element would do nothing because you cannot have delete markers.

When you specify this lifecycle action, the rule cannot specify a tag-based filter.

Type: String

Valid Values: true or false

Ancestor: Expiration

Yes, if Date and Days are absent.
NoncurrentDays

Specifies the number of days an object is non-current before performing the associated action.

Type: Positive Integer

Ancestor: NoncurrentVersionExpiration

Yes
NoncurrentVersionExpiration

Specifies when noncurrent object versions expire. Upon expiration, the noncurrent object versions are permanently deleted.

You set this lifecycle configuration action on a bucket that has versioning enabled (or suspended).

Type: Container

Children: NoncurrentDays

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 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, the rule is executed when condition occurs.

Type: String

Ancestor: Rule

Valid Values: Enabled or Disabled.

Yes
StorageClass

Specifies the storage class (Zenko location) to which you want the object to transition.

Type: String

Ancestor: Transition

Valid Values: Any defined location

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 an object can transition to another storage class.

If versioning has never been enabled on the bucket, the object will transition to the specified storage class.

Otherwise, when your bucket is versioning-enabled or versioning-suspended, only the current version transitions to the specified storage class. Noncurrent versions are unaffected.

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

Requests

Request Syntax

PUT /?lifecycle HTTP/1.1
Host: {{BucketName}}.{{StorageService}}.com
Content-Length: {{length}}
Date: {{date}}
Authorization: {{authorizationString}}
Content-MD5: MD5

Request Parameters

The PUT Bucket Lifecycle operation does not use request parameters.

Request Headers

Name Type Required
Content MD-5

The base64-encoded 128-bit MD5 digest of the data; 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 Elements

The lifecycle configuration can be specified in the request body. The configuration is specified as XML consisting of one or more rules.

<LifecycleConfiguration>
  <Rule>
  ...
  </Rule>
  <Rule>
  ...
  </Rule>
</LifecycleConfiguration>

Responses

Response Headers

Implementation of the PUT Bucket Lifecycle operation uses only response headers that are common to most responses (see Common Response Headers).

Response Elements

The PUT Bucket Lifecycle operation does not return response elements.

Special Errors

The PUT Bucket Lifecycle operation does not return special errors.

Examples

Add lifecycle configuration—bucket versioning disabled

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

  • The Transition action specifies objects with the “documents/” prefix
    to transition to the wasabi_cloud storage class 30 days after creation.
  • The Expiration action specifies objects with the “logs/” prefix to be
    deleted 365 days after creation.
<LifecycleConfiguration>
  <Rule>
    <ID>id1</ID>
    <Filter>
    <Prefix>documents/</Prefix>
    </Filter>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>wasabi_cloud</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.example.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>wasabi_cloud</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

Add lifecycle configuration—bucket versioning is enabled.

The following lifecycle configuration specifies one rule, with one action to perform. Specify this action when your bucket is versioning-enabled or versioning is suspended.

The NoncurrentVersionExpiration action specifies non-current versions of objects with the “logs/” prefix to expire 100 days after the objects become non-current.

<LifeCycleConfiguration>
  <Rule>
    <ID>DeleteAfterBecomingNonCurrent</ID>
    <Filter>
      <Prefix>logs/</Prefix>
    </Filter>
    <Status>Enabled</Status>
    <NoncurrentVersionExpiration>
      <NoncurrentDays>100</NoncurrentDays>
    </NoncurrentVersionExpiration>
  </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.example.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>
</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