aboutsummaryrefslogtreecommitdiff
path: root/doc/book
diff options
context:
space:
mode:
authorAlex <alex@adnab.me>2022-06-15 20:20:28 +0200
committerAlex <alex@adnab.me>2022-06-15 20:20:28 +0200
commit77e3fd6db2c9cd3a10889bd071e95ef839cfbefc (patch)
treeda2c363740505a6aee3821ffec83f2d48169d1d5 /doc/book
parentd544a0e0e03c9b69b226fb5bba2ce27a7af270ca (diff)
downloadgarage-77e3fd6db2c9cd3a10889bd071e95ef839cfbefc.tar.gz
garage-77e3fd6db2c9cd3a10889bd071e95ef839cfbefc.zip
improve internal item counter mechanisms and implement bucket quotas (#326)
- [x] Refactoring of internal counting API - [x] Repair procedure for counters (it's an offline procedure!!!) - [x] New counter for objects in buckets - [x] Add quotas to buckets struct - [x] Add CLI to manage bucket quotas - [x] Add admin API to manage bucket quotas - [x] Apply quotas by adding checks on put operations - [x] Proof-read Co-authored-by: Alex Auvolat <alex@adnab.me> Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/326 Co-authored-by: Alex <alex@adnab.me> Co-committed-by: Alex <alex@adnab.me>
Diffstat (limited to 'doc/book')
-rw-r--r--doc/book/reference-manual/admin-api.md158
1 files changed, 88 insertions, 70 deletions
diff --git a/doc/book/reference-manual/admin-api.md b/doc/book/reference-manual/admin-api.md
index b77f0d39..c7316cdf 100644
--- a/doc/book/reference-manual/admin-api.md
+++ b/doc/book/reference-manual/admin-api.md
@@ -134,8 +134,8 @@ Example request body:
```json
[
- "ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f@10.0.0.11:3901",
- "4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff@10.0.0.12:3901"
+ "ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f@10.0.0.11:3901",
+ "4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff@10.0.0.12:3901"
]
```
@@ -145,14 +145,14 @@ Example response:
```json
[
- {
- "success": true,
- "error": null
- },
- {
- "success": false,
- "error": "Handshake error"
- }
+ {
+ "success": true,
+ "error": null
+ },
+ {
+ "success": false,
+ "error": "Handshake error"
+ }
]
```
@@ -301,7 +301,7 @@ Request body format:
```json
{
- "name": "NameOfMyKey"
+ "name": "NameOfMyKey"
}
```
@@ -313,9 +313,9 @@ Request body format:
```json
{
- "accessKeyId": "GK31c2f218a2e44f485b94239e",
- "secretAccessKey": "b892c0665f0ada8a4755dae98baa3b133590e11dae3bcc1f9d769d67f16c3835",
- "name": "NameOfMyKey"
+ "accessKeyId": "GK31c2f218a2e44f485b94239e",
+ "secretAccessKey": "b892c0665f0ada8a4755dae98baa3b133590e11dae3bcc1f9d769d67f16c3835",
+ "name": "NameOfMyKey"
}
```
@@ -403,11 +403,11 @@ Request body format:
```json
{
- "name": "NameOfMyKey",
- "allow": {
- "createBucket": true,
- },
- "deny": {}
+ "name": "NameOfMyKey",
+ "allow": {
+ "createBucket": true,
+ },
+ "deny": {}
}
```
@@ -473,24 +473,31 @@ Example response:
```json
{
- "id": "e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b",
- "globalAliases": [
- "alex"
- ],
- "keys": [
- {
- "accessKeyId": "GK31c2f218a2e44f485b94239e",
- "name": "alex",
- "permissions": {
- "read": true,
- "write": true,
- "owner": true
- },
- "bucketLocalAliases": [
- "test"
- ]
- }
- ]
+ "id": "afa8f0a22b40b1247ccd0affb869b0af5cff980924a20e4b5e0720a44deb8d39",
+ "globalAliases": [],
+ "websiteAccess": false,
+ "websiteConfig": null,
+ "keys": [
+ {
+ "accessKeyId": "GK31c2f218a2e44f485b94239e",
+ "name": "Imported key",
+ "permissions": {
+ "read": true,
+ "write": true,
+ "owner": true
+ },
+ "bucketLocalAliases": [
+ "debug"
+ ]
+ }
+ ],
+ "objects": 14827,
+ "bytes": 13189855625,
+ "unfinshedUploads": 0,
+ "quotas": {
+ "maxSize": null,
+ "maxObjects": null
+ }
}
```
@@ -502,7 +509,7 @@ Request body format:
```json
{
- "globalAlias": "NameOfMyBucket"
+ "globalAlias": "NameOfMyBucket"
}
```
@@ -510,15 +517,15 @@ OR
```json
{
- "localAlias": {
- "accessKeyId": "GK31c2f218a2e44f485b94239e",
- "alias": "NameOfMyBucket",
- "allow": {
- "read": true,
- "write": true,
- "owner": false
- }
- }
+ "localAlias": {
+ "accessKeyId": "GK31c2f218a2e44f485b94239e",
+ "alias": "NameOfMyBucket",
+ "allow": {
+ "read": true,
+ "write": true,
+ "owner": false
+ }
+ }
}
```
@@ -540,26 +547,37 @@ Deletes a storage bucket. A bucket cannot be deleted if it is not empty.
Warning: this will delete all aliases associated with the bucket!
-#### PutBucketWebsite `PUT /v0/bucket/website?id=<bucket id>`
+#### UpdateBucket `PUT /v0/bucket?id=<bucket id>`
-Sets the website configuration for a bucket (this also enables website access for this bucket).
+Updates configuration of the given bucket.
Request body format:
```json
{
- "indexDocument": "index.html",
- "errorDocument": "404.html"
+ "websiteAccess": {
+ "enabled": true,
+ "indexDocument": "index.html",
+ "errorDocument": "404.html"
+ },
+ "quotas": {
+ "maxSize": 19029801,
+ "maxObjects": null,
+ }
}
```
-The field `errorDocument` is optional, if no error document is set a generic error message is displayed when errors happen.
-
-
-#### DeleteBucketWebsite `DELETE /v0/bucket/website?id=<bucket id>`
+All fields (`websiteAccess` and `quotas`) are optionnal.
+If they are present, the corresponding modifications are applied to the bucket, otherwise nothing is changed.
-Deletes the website configuration for a bucket (disables website access for this bucket).
+In `websiteAccess`: if `enabled` is `true`, `indexDocument` must be specified.
+The field `errorDocument` is optional, if no error document is set a generic
+error message is displayed when errors happen. Conversely, if `enabled` is
+`false`, neither `indexDocument` nor `errorDocument` must be specified.
+In `quotas`: new values of `maxSize` and `maxObjects` must both be specified, or set to `null`
+to remove the quotas. An absent value will be considered the same as a `null`. It is not possible
+to change only one of the two quotas.
### Operations on permissions for keys on buckets
@@ -571,13 +589,13 @@ Request body format:
```json
{
- "bucketId": "e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b",
- "accessKeyId": "GK31c2f218a2e44f485b94239e",
- "permissions": {
- "read": true,
- "write": true,
- "owner": true
- },
+ "bucketId": "e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b",
+ "accessKeyId": "GK31c2f218a2e44f485b94239e",
+ "permissions": {
+ "read": true,
+ "write": true,
+ "owner": true
+ },
}
```
@@ -592,13 +610,13 @@ Request body format:
```json
{
- "bucketId": "e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b",
- "accessKeyId": "GK31c2f218a2e44f485b94239e",
- "permissions": {
- "read": false,
- "write": false,
- "owner": true
- },
+ "bucketId": "e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b",
+ "accessKeyId": "GK31c2f218a2e44f485b94239e",
+ "permissions": {
+ "read": false,
+ "write": false,
+ "owner": true
+ },
}
```