Consistency controls

Consistency controls let you make a trade-off between the availability of the objects and the consistency of those objects across different Storage Nodes and sites, as required by your application.

By default, StorageGRID Webscale guarantees read-after-write consistency for newly created objects. Any GET following a successfully completed PUT will be able to read the newly written data. Overwrites of existing objects, metadata updates, and deletes are eventually consistent. Overwrites generally take seconds or minutes to propagate, but can take up to 15 days.

If you want to perform object operations at a different consistency level, you can specify a consistency control for each bucket or for each API operation.

Consistency controls

You can set the consistency control for a bucket or an API operation to one of the following values:

Consistency control Description
all Provides the highest guarantee of read-after-write consistency. All nodes receive the data immediately, or the request will fail.
strong-global Guarantees read-after-write consistency for all client requests across all sites.
strong-site Guarantees read-after-write consistency for all client requests within a site.
read-after-new-write (Default) Provides read-after-write consistency for new objects and eventual consistency for object updates. Offers high availability and data protection guarantees. Matches AWS S3 consistency guarantees.
Note: If your application uses HEAD requests on objects that do not exist, you might receive a high number of 500 Internal Server errors if one or more Storage Nodes are unavailable. To prevent these errors, set the consistency control to "available" unless you require consistency guarantees similar to AWS S3.
available (eventual consistency for HEAD operations) Behaves the same as the "read-after-new-write" consistency level, but only provides eventual consistency for HEAD operations. Offers higher availability for HEAD operations than "read-after-new-write" if Storage Nodes are unavailable. Differs from AWS S3 consistency guarantees for HEAD operations only.
weak Provides eventual consistency and high availability, with minimal data protection guarantees, especially if a Storage Node fails or is unavailable. Suitable only for write-heavy workloads that require high availability, do not require read-after-write consistency, and can tolerate the potential loss of data if a node fails.

Using the "read-after-new-write" and "available" consistency controls

When a HEAD or GET operation uses the "read-after-new-write" consistency control or a GET operation uses the "available" consistency control, StorageGRID Webscale performs the lookup in multiple steps, as follows:
  • It first looks up the object using a low consistency.
  • If that lookup fails, it repeats the lookup at the next consistency level until it reaches the highest consistency level, "all," which requires all copies of the object metadata to be available.

If a HEAD or GET operation uses the "read-after-new-write" consistency control but the object does not exist, the object lookup will always reach the "all" consistency level. Because this consistency level requires all copies of the object metadata to be available, you can receive a high number of 500 Internal Server errors if one or more Storage Nodes are unavailable.

Unless you require consistency guarantees similar to AWS S3, you can prevent these errors for HEAD operations by setting the consistency control to "available." When a HEAD operation uses the "available" consistency control, StorageGRID Webscale provides eventual consistency only. It does not retry a failed operation until it reaches the "all" consistency level, so it does not require that all copies of the object metadata be available.

Specifying the consistency control for an API operation

To set the consistency control for an individual API operation, consistency controls must be supported for the operation, and you must specify the consistency control in the request header. This example sets the consistency control to "strong-site" for a GET Object operation.

GET /bucket/object HTTP/1.1
Date: date
Authorization: authorization name
Host: host
Consistency-Control: strong-site
Note: You must use the same consistency control for both the PUT Object and GET Object operations. For example, using "weak" to write an object and then using "strong-global" to read the same object back does not provide strong consistency across all sites.

Specifying the consistency control for a bucket

To set the consistency control for bucket, you can use the StorageGRID Webscale PUT Bucket consistency request and the GET Bucket consistency request. Or you can use the the Tenant Manager or the Tenant Management API.

When setting the consistency controls for a bucket, be aware of the following: