mirror of
https://github.com/seaweedfs/seaweedfs.git
synced 2026-10-09 07:47:54 +02:00
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
1 parent
f804014bef
commit
6d2b1f5ae5
2 files changed
+67
No files matched your search
@@ -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 |
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user