PUT Bucket compliance request

The PUT Bucket compliance request allows you to modify the compliance settings for an existing bucket that was created to be compliant. For example, you might want to place a bucket on legal hold or increase its retention period. You cannot decrease a bucket's retention period

To create a compliant bucket, you must use the PUT Bucket request with the custom SGCompliance XML request element, the Tenant Manager, or the Tenant Management API

Note: For more information about configuring compliance and to learn how compliance settings affect ILM rules and policies, see information about administering StorageGRID Webscale.

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

You must specify a value for every field of the compliance settings when issuing a PUT Bucket compliance request.

Request example

This example request modifies the compliance settings for the bucket named mybucket. In this example, objects in mybucket will now be retained for two years (1,051,200 minutes) instead of one year, starting from when the object is ingested into the grid. There is no legal hold on this bucket. Each object will be automatically deleted after two years.

PUT /mybucket/?x-ntap-sg-compliance HTTP/1.1
Date: date
Authorization: authorization name
Host: host
Content-Length: 152

<SGCompliance>
  <RetentionPeriodMinutes>1051200</RetentionPeriodMinutes>
  <LegalHold>false</LegalHold>
  <AutoDelete>true</AutoDelete>
</SGCompliance>
Name Description
RetentionPeriodMinutes The length of the retention period for objects added to this bucket, in minutes. The retention period starts when the object is ingested into the grid.
Attention: When specifying a new value for RetentionPeriodMinutes, you must specify a value that is equal to or greater than the bucket's current retention period. After the bucket's retention period is set, you cannot decrease that value; you can only increase it.
LegalHold
  • True: This bucket is currently under a legal hold. Objects in this bucket cannot be deleted until the legal hold is lifted, even if their retention period has expired.
  • False: This bucket is not currently under a legal hold. Objects in this bucket can be deleted when their retention period expires.
AutoDelete
  • True: The objects in this bucket will be deleted automatically when their retention period expires, unless the bucket is under a legal hold.
  • False: The objects in this bucket will not be deleted automatically when the retention period expires. You must delete these objects manually if you need to delete them.

Consistency level for compliance settings

When you update the compliance settings for an S3 bucket with a PUT Bucket compliance request, StorageGRID Webscale attempts to update the bucket's metadata across the grid. By default, StorageGRID Webscale uses the strong-global consistency level to guarantee that all data center sites and all Storage Nodes that contain bucket metadata have read-after-write consistency for the changed compliance settings.

If StorageGRID Webscale cannot achieve the strong-global consistency level because a data center site or multiple Storage Nodes at a site are unavailable, the HTTP status code for the response is 503 Service Unavailable.

If you receive this response, you must contact the grid administrator to ensure that the required storage services are made available as soon as possible. If the grid administrator is unable to make enough of the Storage Nodes at each site available, technical support might direct you to retry the failed request by forcing the strong-site consistency level.

Attention: Never force the strong-site consistency level for PUT bucket compliance unless you have been directed to do so by technical support and unless you understand the potential consequences of using this level.

When the consistency level is reduced to strong-site, StorageGRID Webscale guarantees that updated compliance settings will have read-after-write consistency only for client requests within a site. This means that the StorageGRID Webscale system might temporarily have multiple, inconsistent settings for this bucket until all sites and Storage Nodes are available. The inconsistent settings can result in unexpected and undesired behavior. For example, if you are placing a bucket under a legal hold and you force a lower consistency level, the bucket's previous compliance settings (that is, legal hold off) might continue to be in effect at some data center sites. As a result, objects that you think are on legal hold might be deleted when their retention period expires, either by the user or by AutoDelete, if enabled.

To force the use of the strong-site consistency level, reissue the PUT Bucket compliance request and include the Consistency-Control HTTP request header, as follows:

PUT /mybucket/?x-ntap-sg-compliance HTTP/1.1
Consistency-Control: strong-site

Error responses

  • If the bucket was not created to be compliant, the HTTP status code for the response is 404 Not Found.
  • If RetentionPeriodMinutes in the request is less than the bucket's current retention period, the HTTP status code is 400 Bad Request.