Operations on buckets

The StorageGRID Webscale system supports a maximum of 1000 buckets per 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. For information on using the Consistency-Control header, see How StorageGRID Webscale implements the S3 REST API.

You can check whether updates to last access time are enabled or disabled for individual buckets. For more information, see GET Bucket last access time request.

For other bucket operations, see "Custom operations on buckets."

The following table describes which operations on buckets are implemented, and how they are implemented, in the StorageGRID Webscale system.

Operation Implementation
DELETE Bucket Implemented with all Amazon S3 REST API behavior.
DELETE Bucket policy If the necessary access credentials are provided for the account, this operation deletes the policy attached to the bucket. For information about the policy language supported by the StorageGRID Webscale system, see Bucket and group access policies.
DELETE Bucket replication If the necessary access credentials are provided for the account, the operation deletes the replication configuration attached to the bucket.
GET Bucket (List Objects) If the necessary access credentials are provided for the account, 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 when the object was ingested with the REDUCED_REDUNDANCY storage class specified. When an object is ingested into StorageGRID Webscale with the REDUCED_REDUNDANCY storage class, it means that the object is ingested using a single-commit ingest operation. It does not result in the object being stored at lower levels of redundancy in the StorageGRID Webscale system.

CAUTION:
Be careful when ingesting objects using REDUCED_REDUNDANCY to create only a single initial copy of the object data. If the single copy is created on a Storage Node that fails, and ILM is not yet satisfied, the result is unrecoverable loss of data.

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 If the necessary access credentials are provided for the account, 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 location If the necessary access credentials are provided for the account, this operation will return 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 If the necessary access credentials are provided for the account, this operation returns the notification configuration attached to the bucket.
GET Bucket policy If the necessary access credentials are provided for the account, this operation returns the policy attached to the bucket. For information about the policy language supported by the StorageGRID Webscale system, see Bucket and group access policies.
GET Bucket replication If the necessary access credentials are provided for the account, 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. To retrieve the versioning state of a bucket, you must be the bucket owner. The versioning state returned indicates if the bucket is "Unversioned" or if the bucket is version "Enabled" or "Suspended".

HEAD Bucket If the necessary access credentials are provided for the account, this operation determines if a bucket exists and you have permission to access it.
PUT Bucket If the necessary access credentials are provided for the account, this operation creates a new bucket. By creating the bucket, you become the bucket owner.
By default, buckets are created in the us-east-1 region. To specify a different region, use the LocationConstraint request element, and specify the exact name of a region that has been defined using the StorageGRID Webscale Grid Management Interface or the 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.
PUT Bucket notification If the necessary access credentials are provided for the account, this operation configures notifications for the bucket using the notification configuration XML included in the request body.
Attention: StorageGRID Webscale 11.0 includes the initial release of platform services. CloudMirror replication, notifications, and search integration are currently appropriate only for specific situations and workloads. You must contact your NetApp representative if you want to use the initial release of these services.
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 Management Interface 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

Consult theTenant Administrator Guide for more information on implementing notifications on S3 buckets.

PUT Bucket policy If the necessary access credentials are provided for the account, this operation sets the policy attached to the bucket. For information about the policy language supported by the StorageGRID Webscale system, see Bucket and group access policies.
PUT Bucket replication If the necessary access credentials are provided for the account, this operation configures StorageGRID Webscale CloudMirror replication for the bucket using the replication configuration XML provided in the request body.
Attention: StorageGRID Webscale 11.0 includes the initial release of platform services. CloudMirror replication, notifications, and search integration are currently appropriate only for specific situations and workloads. You must contact your NetApp representative if you want to use the initial release of these services.
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 Management Interfaceor the Tenant Management API.

    The endpoint must exist for replication configuration to succeed. If the endpoint does not exist, a 404 Not Found message is returned with the code NoSuchEndpoint.

  • You do not need to specify a Role or StorageClass in the configuration XML, as these values are not used by StorageGRID Webscale and will be ignored if submitted. StorageGRID Webscale does not need a role defined to enable it to store replicated objects to the destination bucket, and uses the STANDARD storage class by default.

Consult theTenant Administrator Guide for more information on using bucket replication to implement StorageGRID Webscale CloudMirror replication.

PUT Bucket versioning

This implementation uses the versioning subresource to set the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner. 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.