PUT Bucket request modifications for compliance

The SGCompliance XML element is a StorageGRID Webscale custom element that you can include in the optional XML request body of PUT Bucket requests to create compliant buckets and set compliance settings.

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

If the PUT Bucket request body does not include the SGCompliance XML element, compliance will not be enabled for the bucket. If the PUT Bucket request body includes the SGCompliance XML element, you must specify a value for all child elements.

When compliance is enabled for a bucket, you cannot:
  • Enable bucket versioning
  • Modify an existing object's data, user-defined metadata, or S3 object tagging
When an object's age is within the retention period, or when legal hold is enabled for the bucket, you cannot:
  • Delete the object

When using the LocationConstraint element, you must specify the exact name of a region that has been defined using the Grid Manager or the Grid Management API. Contact your system administrator if you do not know the region name you should use.

Note: An error will occur if your PUT Bucket request uses a region that has not been defined in StorageGRID Webscale.

For more information about configuring compliance and to learn how compliance settings affect information lifecycle management (ILM) rules, see information about administering StorageGRID Webscale.

Request example

This example request creates a compliant bucket named mybucket in the default region, us-east-1. In this example, objects in mybucket will be retained for one year (525,600 minutes), starting from when each object is ingested into the grid. There is no legal hold on this bucket. Each object will be automatically deleted after one year.

PUT /mybucket HTTP/1.1
Date: date
Authorization: authorization name
Host: host
Content-Length: 272

<CreateBucketConfiguration>
  <LocationConstraint>us-east-1</LocationConstraint>
  <SGCompliance>
    <RetentionPeriodMinutes>525600</RetentionPeriodMinutes>
    <LegalHold>false</LegalHold>
    <AutoDelete>true</AutoDelete>
  </SGCompliance>
</CreateBucketConfiguration>
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.

You can specify any non-zero positive integer as the value.

Attention: After the bucket's retention period is set, you cannot decrease that value; you can only increase it.
Note: If you want to test compliance settings before implementing this feature in a production-level grid, you can set RetentionPeriodMinutes to a small value. However, be aware that it will take longer than an hour to automatically delete objects in compliant buckets, even if the retention period is very short. This is because of the delays due to ILM scanning.
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.

Error responses

If a PUT Bucket request attempts to remove the compliance settings of an existing compliant bucket or add compliance settings to an existing non-compliant bucket, the HTTP status code for the response is 409 Conflict.

If one of the compliance elements has malformed XML or invalid values, the HTTP status code for the response is 400 Bad Request.