Object Expiration

Some objects that you store in an S3 bucket might have a well-defined lifetime. For example, you might be uploading periodic logs to your bucket. After a period of time, you might not need to retain those log objects. In the past, you were responsible for deleting such objects when you no longer needed them. Now you can use Object Expiration to specify a lifetime for objects in your bucket.

With Object Expiration, when an object reaches the end of its lifetime, Amazon S3 queues it for removal and removes it asynchronously. There may be a small lag between the expiration date and the date at which Amazon S3 removes an object. You are not charged for storage time associated with an object that has expired.

To set an object’s expiration, you add a lifecycle configuration to your bucket, which describes the lifetime of various objects in your bucket. A lifecycle configuration can have up to 100 rules. Each rule identifies an object prefix and a lifetime for objects that begin with this prefix. The lifetime is the number of days since creation when you want the object removed.

The lifetime value must be a non-zero positive integer. Amazon S3 calculates expiration time by adding the expiration period specified in the rule to the object creation time and rounding the resulting time to the next day midnight GMT. For example, if an object was created on 1/15/2012 10:30 am GMT and the expiration period was specified as 3 days, then the expiration date of the object would be calculated as 1/19/2012 00:00 GMT.

	Note
	Whenever you overwrite an object, Amazon S3 resets its creation date/time to the date and time you updated the object. Accordingly, Amazon S3 also updates the object's expiration date from this new creation date/time.

The prefix is same that you specify when you list objects as described in the list objects API. For more information, go to GET Bucket (List Objects). If you specify a key prefix, the rule applies to all objects whose key names begin with that prefix. After that the objects expire and Amazon S3 removes them from your bucket.

Amazon S3 stores the lifecycle configuration in the lifecycle subresource on your bucket. You can use the AWS Management Console to add, update, or delete object expiration rules. Amazon S3 evaluates these rules daily and queues expired objects for removal.

When you add the lifecycle configuration to a bucket, the configuration rules apply to both existing objects and new objects you add later. For example, if you add a lifecycle configuration today that causes objects with a specific prefix to expire 30 days after the object's creation, Amazon S3 will queue for removal any existing objects that are more than 30 days old.

To find when an object is scheduled to expire, you can use the GET Object or the HEAD object APIs. These APIs return response headers that provide object expiration information. For more information go to HEAD Object and GET Object in the Amazon Simple Storage Service API Reference.

To find when an object was removed by Amazon S3 you can use Amazon S3 server access logs. The value "S3.EXPIRE.OBJECT" of the operation field in the log record indicates that Amazon S3 initiated the operation. For more information, see Server Access Logging.

	Note
	If your bucket is version-enabled (see Object Versioning) or versioning is suspended, you cannot add lifecycle configuration to the bucket.

You can delete objects by explicitly calling the DELETE Object API or configure lifecycle to enable Amazon S3 to remove them for you. If you want to block users or accounts from removing or deleting objects from your bucket you must deny them s3:DeleteObject, s3:DeleteObjectVersion and s3:PutLifecycleConfiguration actions.

The following examples explain how to create and manage a lifecycle configuration.

<LifecycleConfiguration>
  <Rule>
    <ID>Yearly photos expiration rule</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>365</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

Example 2. Set object expiration - Specify all objects in the bucket

To apply a single rule to all objects in a bucket, you provide an empty Prefix attribute. For example, the following lifecycle configuration sets all the objects to expire 3650 days after creation.

<LifecycleConfiguration>
  <Rule>
    <ID>10 year all objects expire rule</ID>
    <Prefix></Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>3650</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

	Caution
	When you specify an empty prefix, it applies to all objects in the bucket. Amazon S3 deletes any object that expires based on the rule.

<LifecycleConfiguration>
  <Rule>
    <ID>30 days log objects expire rule</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>30</Days>
    </Expiration>
  </Rule>
  <Rule>
    <ID>1 year documents expire rule</ID>
    <Prefix>documents/</Prefix>
    <Status>Disabled</Status>
    <Expiration>
      <Days>365</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

<LifecycleConfiguration>
  <Rule>
    <ID>111</ID>
    <Prefix>documents</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>30</Days>
    </Expiration>
  </Rule>
  <Rule>
    <ID>222</ID>
    <Prefix>documents/2011</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>365</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>