From 6d2b1f5ae5ae51048ed72738fac198f435a8d91e Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Fri, 11 Sep 2026 19:15:54 -0700
Subject: [PATCH] docs: add S3 ?seaweedfs-quota extension to quota and S3 API
 wiki pages

Document the new S3 subresource for bucket quota management:
- Add S3 API extension section to S3-Bucket-Quota.md with API spec,
  auth, authorization, curl example, and comparison with MinIO/Ceph
- Add SeaweedFS Extensions section to Amazon-S3-API.md listing
  ?seaweedfs-quota as a non-standard S3 subresource
---
 Amazon-S3-API.md   |  8 +++++++
 S3-Bucket-Quota.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)

diff --git a/Amazon-S3-API.md b/Amazon-S3-API.md
index bafb70d..3e5e6ba 100644
--- a/Amazon-S3-API.md
+++ b/Amazon-S3-API.md
@@ -171,6 +171,14 @@ SeaweedFS also implements these related AWS service APIs on the same S3 endpoint
 | IAM API | User, policy, access key, and group management | [[Amazon IAM API]], [[AWS IAM CLI]] |
 | S3 Tables | Table bucket, namespace, and table management (Apache Iceberg) | [[S3 Table Bucket]] |
 
+## SeaweedFS Extensions
+
+These are SeaweedFS-specific S3 subresources, not part of the AWS S3 API. They use the same S3 endpoint and SigV4 authentication but are not callable by standard AWS tools (`aws s3api`, `s3cmd`, `rclone`). Use any SigV4-capable HTTP client.
+
+| Subresource | Operations | IAM Permission | Documentation |
+|---|---|---|---|
+| `?seaweedfs-quota` | `PUT /{bucket}?seaweedfs-quota`, `GET /{bucket}?seaweedfs-quota` | `s3:PutBucketQuota`, `s3:GetBucketQuota` | [[S3 Bucket Quota]] |
+
 # Feature Differences
 
 | Feature | SeaweedFS | Amazon S3 |
diff --git a/S3-Bucket-Quota.md b/S3-Bucket-Quota.md
index 6074dd7..b887fe8 100644
--- a/S3-Bucket-Quota.md
+++ b/S3-Bucket-Quota.md
@@ -64,3 +64,62 @@ Note: Internally this readOnly flag is saved into filer configuration for `locat
 # Schedule Quota Enforcement
 
 `s3.bucket.quota.enforce -apply` should be run regularly. You can add it to the `master.toml` file, or add it to some shell scripts. The frequency depends on how much you trust your users. :)
+
+# S3 API Extension (`?seaweedfs-quota`)
+
+In addition to `weed shell`, bucket quota can be configured via the S3 API using a SeaweedFS-specific subresource. This is useful for programmatic integration (e.g., Apache CloudStack) where the integrator can sign SigV4 requests but cannot run `weed shell`.
+
+## API
+
+```
+PUT /{bucket}?seaweedfs-quota    — set bucket quota (IAM: s3:PutBucketQuota)
+GET /{bucket}?seaweedfs-quota    — get bucket quota (IAM: s3:GetBucketQuota)
+```
+
+Request/response body (JSON):
+```json
+{"quota_size": 100, "quota_unit": "GB", "quota_enabled": true}
+```
+
+Supported `quota_unit` values: `B`, `KB`, `MB`, `GB`, `TB` (case-insensitive).
+
+`quota_enabled: false` with a positive `quota_size` stores the quota as disabled but retains the size. `quota_size: 0` removes the quota entirely. When quota is cleared, the bucket's read-only flag is also lifted.
+
+## Authentication
+
+Uses standard S3 SigV4 — the same credentials used for other S3 operations. No separate admin token is needed.
+
+## Authorization
+
+Two dedicated IAM permissions:
+- `s3:PutBucketQuota` — required to set/clear quota
+- `s3:GetBucketQuota` — required to read quota
+
+This allows scoping a credential to quota management only, without granting bucket deletion, user management, or other admin capabilities.
+
+## Example (curl with SigV4)
+
+Since `?seaweedfs-quota` is a SeaweedFS extension and not part of the AWS S3 API, standard AWS tools (`aws s3api`, `s3cmd`, `rclone`) do not support it directly. Use any SigV4-capable HTTP client or sign the request manually:
+
+```bash
+# Set a 100GB quota on bucket "mybucket"
+curl -X PUT \
+  -H "Content-Type: application/json" \
+  -H "Authorization: AWS4-HMAC-SHA256 ..." \
+  -d '{"quota_size":100,"quota_unit":"GB","quota_enabled":true}' \
+  http://localhost:8333/mybucket?seaweedfs-quota
+
+# Get the current quota
+curl -H "Authorization: AWS4-HMAC-SHA256 ..." \
+  http://localhost:8333/mybucket?seaweedfs-quota
+```
+
+## Comparison with MinIO and Ceph
+
+| Provider | Quota endpoint | Auth | CLI tool | `aws s3api`? |
+|---|---|---|---|---|
+| SeaweedFS | S3 API (`?seaweedfs-quota`) | S3 SigV4 | `weed shell` | No |
+| MinIO | Admin API (separate) | Admin credentials | `mc admin bucket quota` | No |
+| Ceph RGW | Admin Ops API (`/admin/`) | Admin capabilities | `radosgw-admin quota set` | No |
+
+None of the three use standard AWS S3 API for quota. SeaweedFS's approach is the closest to standard S3 because it uses the same endpoint and same SigV4 credentials, just with a custom query parameter.