Skip to main content
A newer release of this product is available.

Use S3 Object Lock default bucket retention

Contributors netapp-madkat
PDFs

If a bucket has S3 Object Lock enabled, you can specify a default retention mode and default retention period that is applied to each object added to the bucket.

  • S3 Object Lock can be enabled or disabled for a bucket during bucket creation.

  • If S3 Object Lock is enabled for a bucket, you can configure default retention for the bucket.

  • Default retention configuration specifies:

    • Default retention mode: StorageGRID supports only “COMPLIANCE” mode.

    • Default retention period in days or years.

GET Object Lock Configuration

The GET Object Lock Configuration request allows you to determine if Object Lock is enabled for a bucket and, if it is enabled, see if there is a default retention mode and retention period configured for the bucket.

When new object versions are ingested to the bucket, the default retention mode is applied if x-amz-object-lock-mode is not specified. The default retention period is used to calculate the retain-until-date if x-amz-object-lock-retain-until-date is not specified.

You must have the s3:GetBucketObjectLockConfiguration permission, or be account root, to complete this operation.

Request example

GET /bucket?object-lock HTTP/1.1
Host: host
Accept-Encoding: identity
User-Agent: aws-cli/1.18.106 Python/3.8.2 Linux/4.4.0-18362-Microsoft botocore/1.17.29
x-amz-date: date
x-amz-content-sha256: authorization string
Authorization: authorization string

Response example

HTTP/1.1 200 OK
x-amz-id-2: iVmcB7OXXJRkRH1FiVq1151/T24gRfpwpuZrEG11Bb9ImOMAAe98oxSpXlknabA0LTvBYJpSIXk=
x-amz-request-id: B34E94CACB2CEF6D
Date: Fri, 04 Sep 2020 22:47:09 GMT
Transfer-Encoding: chunked
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <ObjectLockEnabled>Enabled</ObjectLockEnabled>
    <Rule>
        <DefaultRetention>
            <Mode>COMPLIANCE</Mode>
            <Years>6</Years>
        </DefaultRetention>
    </Rule>
</ObjectLockConfiguration>

PUT Object Lock Configuration

The PUT Object Lock Configuration request allows you to modify the default retention mode and default retention period for a bucket that has Object Lock enabled. You can also remove previously configured default retention settings.

When new object versions are ingested to the bucket, the default retention mode is applied if x-amz-object-lock-mode is not specified. The default retention period is used to calculate the retain-until-date if x-amz-object-lock-retain-until-date is not specified.

If the default retention period is modified after ingest of an object version, the retain-until-date of the object version remains the same and is not recalculated using the new default retention period.

You must have the s3:PutBucketObjectLockConfiguration permission, or be account root, to complete this operation.

The Content-MD5 request header must be specified in the PUT request.

Request example

PUT /bucket?object-lock HTTP/1.1
Accept-Encoding: identity
Content-Length: 308
Host: host
Content-MD5: request header
User-Agent: s3sign/1.0.0 requests/2.24.0 python/3.8.2
X-Amz-Date: date
X-Amz-Content-SHA256: authorization string
Authorization: authorization string

<ObjectLockConfiguration>
    <ObjectLockEnabled>Enabled</ObjectLockEnabled>
    <Rule>
        <DefaultRetention>
            <Mode>COMPLIANCE</Mode>
            <Years>6</Years>
        </DefaultRetention>
    </Rule>
</ObjectLockConfiguration>