S3 Object Lock retention - Amazon Simple Storage Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

S3 Object Lock retention

The Object Lock retention operation allows you to apply retention dates for your objects using either governance mode or compliance mode. These retention modes apply different levels of protection. You can apply either retention mode to any object version. Retention dates, like legal holds, prevent an object from being overwritten or deleted. Amazon S3 stores the retain until date specified in the object’s metadata and protects the specified version of the object version until the retention period expires.

You can use S3 Batch Operations with Object Lock to manage retention dates of many Amazon S3 objects at once. You specify the list of target objects in your manifest and submit it to Batch Operations for completion. For more information, see S3 Object Lock Retention periods.

Your S3 Batch Operations job with retention dates runs until completion, until cancellation, or until a failure state is reached. You should use S3 Batch Operations and S3 Object Lock retention when you want to add, change, or remove the retention date for many objects with a single request.

Batch Operations verifies that Object Lock is enabled on your bucket before processing any keys in the manifest. To perform the operations and validation, Batch Operations needs s3:GetBucketObjectLockConfiguration and s3:PutObjectRetention permissions in an IAM role to allow Batch Operations to call Object Lock on your behalf. For more information, see Object Lock considerations.

For information about using this operation with the REST API, see S3PutObjectRetention in the CreateJob operation in the Amazon Simple Storage Service API Reference.

For an Amazon Command Line Interface example of using this operation, see Using the Amazon SDK for Java. For an Amazon SDK for Java example, see Using the Amazon CLI.

Restrictions and limitations

  • S3 Batch Operations does not make any bucket level changes.

  • Versioning and S3 Object Lock must be configured on the bucket where the job is performed.

  • All objects listed in the manifest must be in the same bucket.

  • The operation works on the latest version of the object unless a version is explicitly specified in the manifest.

  • You need s3:PutObjectRetention permission in your IAM role to use this.

  • s3:GetBucketObjectLockConfiguration IAM permission is required to confirm that Object Lock is enabled for the S3 bucket.

  • You can only extend the retention period of objects with COMPLIANCE mode retention dates applied, and it cannot be shortened.