Tiering doc

Author: efirs

docs/buckets/create-bucket.md

@@ -12,6 +12,12 @@ to a bucket.
 Buckets and the objects in them are private and can be accessed only via access
 keys that you explicitly grant access permissions to.
 
+## Setting bucket tier
+
+When bucket created in the web console, you can set the default object tier for
+all objects uploaded to it. For more information, see the
+[Tiers](../objects/tiers.md) guide.
+
 ## Creating a bucket using flyctl
 
 To create a bucket for one of your Fly apps, run the following command in the

docs/objects/tiers.md

@@ -0,0 +1,93 @@
+# Object storage tiers
+
+Tigris offers object storage tiers to optimize storage costs based on the access
+patterns of your data. There are three storage tiers available:
+
+- Standard
+- Infrequent Access
+- Archive
+
+## Standard tier
+
+The default storage class. It provides high durability, availability, and
+performance for frequently accessed data.
+
+## Infrequent Access tier
+
+Lower-cost storage for data that is accessed less frequently but requires rapid
+access when needed.
+
+## Archive tier
+
+Low-cost storage for data archiving. Long-term data archiving with infrequent
+access. The data is not immediately available for access and requires retrieval
+before it can be accessed. Retrieval times is about 1 hour.
+
+## Setting object tier
+
+Object tier can be set at the object creation time. The default object tier is
+Standard. To set the object tier, use the `--storage-class` flag with the
+`put-object` AWS CLI or corresponding field of PutObject, CreateMultipartUpload
+SDK APIs input. REST API users can set the `x-amz-storage-class` header.
+
+Tigris accepts S3 compatible storage classes:
+
+- STANDARD - for standard
+- STANDARD_IA - for infrequent access
+- GLACIER - for archive
+
+If the object storage class is not specified, it would be placed to the tier
+specified in the
+[bucket configuration](../buckets/create-bucket.md#setting-bucket-tier) during
+bucket creation time.
+
+### Example with AWS CLI
+
+```bash
+aws s3api put-object --bucket my-bucket --key my-object.txt --body bar.txt --storage-class STANDARD_IA
+```
+
+### Example with REST API
+
+```bash
+PUT
+/my-bucket/my-object.txt
+
+host:idev-storage.fly.tigris.dev
+x-amz-storage-class:STANDARD_IA
+...
+```
+
+## Restoring objects from Archive tier
+
+Objects written to the Archive storage class are not immediately available for
+access. Get requests for objects in the Archive storage class will return 403
+(InvalidObjectState) error. To restore objects from the Archive storage class,
+initiate a restore request.
+
+### Initiate restore request
+
+```bash
+aws s3api restore-object --bucket my-bucket --key 'my-archive-object.txt' --restore-request Days=3
+```
+
+The `Days` parameter specifies the number of days the restored object will be
+available for access. After the specified number of days, the object will be
+moved back to the Archive storage class.
+
+### Check restore status
+
+```bash
+aws s3api head-object --bucket my-bucket --key 'my-archive-object.txt'
+```
+
+Ongoing restore requests will have the `Restore: ongoing-request="true"` header
+in the response. Once the restore is complete, the `Restore` header will contain
+the expiry date when the object will be moved back to the Archive storage class:
+
+```bash
+{
+    "Restore": "ongoing-request=\"false\" expiry-date=\"Fri, 01 Nov 2024 02:00:00 GMT\"",
+    "StorageClass": "GLACIER"
+}
+```

sidebars.js

@@ -75,6 +75,7 @@ const sidebars = {
         "objects/upload-via-html-form",
         "objects/access-objects-via-cookies",
         "objects/acl",
+        "objects/tiers",
       ],
     },
     {