Operations on buckets

The StorageGRID Webscale system supports a maximum of 1,000 buckets for each S3 tenant account.

Bucket name restrictions follow the AWS US Standard region restrictions, but you should further restrict them to DNS naming conventions in order to support S3 virtual hosted-style requests.

The GET Bucket (List Objects) and GET Bucket versions operations support StorageGRID Webscale consistency controls.

You can check whether updates to last access time are enabled or disabled for individual buckets.

The following table describes how StorageGRID Webscale implements S3 REST API bucket operations. To perform any of these operations, the necessary access credentials must be provided for the account.

Operation Implementation
DELETE Bucket Implemented with all Amazon S3 REST API behavior.
DELETE Bucket cors This operation deletes the CORS configuration for the bucket.
DELETE Bucket policy This operation deletes the policy attached to the bucket.
DELETE Bucket replication This operation deletes the replication configuration attached to the bucket.
GET Bucket (List Objects), version 1 This operation returns some or all (up to 1,000) of the objects in a bucket.

The Storage Class for objects is always listed as STANDARD, even if the object was ingested with the REDUCED_REDUNDANCY storage class option.

Requests that traverse a large number of keys require special handling. The request might return a truncated response or an empty response to avoid timing out.

To get the complete set of results, you need to continue making requests while updating the marker parameter, as you normally do with a truncated result. Always use NextMarker if it is present. In some cases, the StorageGRID Webscale implementation of the S3 REST API returns a NextMarker, when the Amazon S3 REST API would not, because it is a better marker than the last key returned.

GET Bucket acl This operation returns a positive response and the ID, DisplayName, and Permission of the bucket owner, indicating that the owner has full access to the bucket.
GET Bucket cors This operation returns the cors configuration for the bucket.
GET Bucket location This operation returns the bucket's region. By default, us-east-1 is returned unless a region was set using the LocationConstraint element in the PUT Bucket request.
GET Bucket Object versions

With READ access on a bucket, this operation with the versions subresource lists metadata of all of the versions of objects in the bucket.

GET Bucket notification This operation returns the notification configuration attached to the bucket.
GET Bucket policy This operation returns the policy attached to the bucket.
GET Bucket replication This operation returns the replication configuration attached to the bucket.
GET Bucket versioning

This implementation uses the versioning subresource to return the versioning state of a bucket. The versioning state returned indicates if the bucket is "Unversioned" or if the bucket is version "Enabled" or "Suspended."

HEAD Bucket This operation determines if a bucket exists and you have permission to access it.
PUT Bucket This operation creates a new bucket. By creating the bucket, you become the bucket owner.
  • Bucket names must comply with the following rules:
    • Must be unique across each StorageGRID Webscale system (not just unique within the tenant account).
    • Must be DNS compliant.
    • Must contain between 3 and 63 characters.
    • Can be a series of one or more labels, with adjacent labels separated by a period. Each label must start and end with a lowercase letter or a number and can only use lowercase letters, numbers, and hyphens.
    • Must not look like a text-formatted IP address.
    • Should not use periods in virtual hosted-style requests because periods will cause problems with server wildcard certificate verification.
  • By default, buckets are created in the us-east-1 region; however, you can use the LocationConstraint request element in the request body to specify a different region. 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.
  • When using a PUT Bucket request, you can include the SGCompliance XML element in the XML request body. SGCompliance is a custom StorageGRID Webscale element that allows you to create buckets that are compliant.

PUT Bucket cors This operation sets the CORS configuration for a bucket so that the bucket can service cross-origin requests.

Cross-origin resource sharing (CORS) is a security mechanism that allows client web applications in one domain to access resources in a different domain. For example, suppose you use an S3 bucket named images to store graphics. By setting the CORS configuration for the images bucket, you can allow the images in that bucket to be displayed on the website http://www.example.com.

PUT Bucket notification This operation configures notifications for the bucket using the notification configuration XML included in the request body.
You should be aware of the following implementation details:
  • StorageGRID Webscale supports Simple Notification Service (SNS) topics as destinations. Simple Queue Service (SQS) or Amazon Lambda endpoints are not supported.
  • The destination for notifications must be specified as the URN of an StorageGRID Webscale endpoint. Endpoints can be created using the Tenant Manager or the Tenant Management API.

    The endpoint must exist for notification configuration to succeed. If the endpoint does not exist, a 400 Bad Request error is returned with the code InvalidArgument.

  • Notifications on the s3:ReducedRedundancyLostObject event are not supported.
  • Event notification messages use standard values for most keys, except for the following:
    • eventSource returns sgws:s3
    • awsRegion: this key is not returned
    • x-amz-id-2: this key is not returned
    • arn returns urn:sgws:s3:::bucket-name
PUT Bucket policy This operation sets the policy attached to the bucket.
PUT Bucket replication This operation configures StorageGRID Webscale CloudMirror replication for the bucket using the replication configuration XML provided in the request body.
For CloudMirror replication, you should be aware of the following implementation details:
  • Bucket replication can be configured on versioned or unversioned buckets.
  • You can specify a different destination bucket in each rule of the replication configuration XML. A source bucket can replicate to more than one destination bucket.
  • Destination buckets must be specified as the URN of StorageGRID Webscale endpoints as specified in the Tenant Manager or the Tenant Management API.

    The endpoint must exist for replication configuration to succeed. If the endpoint does not exist, the request fails as a 400 Bad Request. The error message states: Unable to save the replication policy. The specified endpoint URN does not exist: URN.

  • You do not need to specify a Role in the configuration XML. This value is not used by StorageGRID Webscale and will be ignored if submitted.
  • If you omit the storage class from the configuration XML, StorageGRID Webscale uses the STANDARD storage class by default.
  • If you delete an object from the source bucket or you delete the source bucket itself, the cross-region replication behavior is as follows:
    • If you delete the object or bucket before it has been replicated, the object/bucket is not replicated and you are not notified.
    • If you delete the object or bucket after it has been replicated, StorageGRID Webscale follows standard Amazon S3 delete behavior for cross-region replication.
PUT Bucket versioning

This implementation uses the versioning subresource to set the versioning state of an existing bucket. You can set the versioning state with one of the following values:

  • Enabled: Enables versioning for the objects in the bucket. All objects added to the bucket receive a unique version ID.
  • Suspended: Disables versioning for the objects in the bucket. All objects added to the bucket receive the version ID null.