aboutsummaryrefslogtreecommitdiff
path: root/doc/api/garage-admin-v1.yml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/garage-admin-v1.yml')
-rw-r--r--doc/api/garage-admin-v1.yml47
1 files changed, 41 insertions, 6 deletions
diff --git a/doc/api/garage-admin-v1.yml b/doc/api/garage-admin-v1.yml
index ec9a77f8..9fb57e11 100644
--- a/doc/api/garage-admin-v1.yml
+++ b/doc/api/garage-admin-v1.yml
@@ -19,6 +19,8 @@ paths:
- Live nodes
- Currently configured cluster layout
- Staged changes to the cluster layout
+
+ *Capacity is given in bytes*
responses:
'500':
description: |
@@ -142,6 +144,7 @@ paths:
- Currently configured cluster layout
- Staged changes to the cluster layout
+ *Capacity is given in bytes*
*The info returned by this endpoint is a subset of the info returned by `GET /status`.*
responses:
'500':
@@ -164,7 +167,12 @@ paths:
summary: "Send modifications to the cluster layout"
description: |
Send modifications to the cluster layout. These modifications will be included in the staged role changes, visible in subsequent calls of `GET /layout`. Once the set of staged changes is satisfactory, the user may call `POST /layout/apply` to apply the changed changes, or `POST /layout/revert` to clear all of the staged changes in the layout.
- Note that setting the capacity to `null` will configure the node as a gateway.
+
+ Setting the capacity to `null` will configure the node as a gateway.
+ Otherwise, capacity must be now set in bytes (before Garage 0.9 it was arbitrary weights).
+ For example to declare 100GB, you must set `capacity: 100000000000`.
+
+ Garage uses internally the International System of Units (SI), it assumes that 1kB = 1000 bytes, and displays storage as kB, MB, GB (and not KiB, MiB, GiB that assume 1KiB = 1024 bytes).
requestBody:
description: |
To add a new node to the layout or to change the configuration of an existing node, simply set the values you want (`zone`, `capacity`, and `tags`).
@@ -180,7 +188,7 @@ paths:
example:
- id: "e2ee7984ee65b260682086ec70026165903c86e601a4a5a501c1900afe28d84b"
zone: "geneva"
- capacity: 8
+ capacity: 100000000000
tags:
- gateway
- id: "4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff"
@@ -207,6 +215,8 @@ paths:
summary: "Apply staged layout"
description: |
Applies to the cluster the layout changes currently registered as staged layout changes.
+
+ *Note: do not try to parse the `message` field of the response, it is given as an array of string specifically because its format is not stable.*
requestBody:
description: |
Similarly to the CLI, the body must include the version of the new layout that will be created, which MUST be 1 + the value of the currently existing layout in the cluster.
@@ -223,6 +233,31 @@ paths:
description: "Invalid syntax or requested change"
'200':
description: "The staged layout has been applied as the new layout of the cluster, a rebalance has been triggered."
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [ message, layout ]
+ properties:
+ message:
+ type: array
+ items:
+ type: string
+ example:
+ - "==== COMPUTATION OF A NEW PARTITION ASSIGNATION ===="
+ - ""
+ - "Partitions are replicated 1 times on at least 1 distinct zones."
+ - ""
+ - "Optimal partition size: 419.4 MB (3 B in previous layout)"
+ - "Usable capacity / total cluster capacity: 107.4 GB / 107.4 GB (100.0 %)"
+ - "Effective capacity (replication factor 1): 107.4 GB"
+ - ""
+ - "A total of 0 new copies of partitions need to be transferred."
+ - ""
+ - "dc1 Tags Partitions Capacity Usable capacity\n 6a8e08af2aab1083 a,v 256 (0 new) 107.4 GB 107.4 GB (100.0%)\n TOTAL 256 (256 unique) 107.4 GB 107.4 GB (100.0%)\n\n"
+ layout:
+ $ref: '#/components/schemas/ClusterLayout'
+
/layout/revert:
post:
@@ -1097,7 +1132,7 @@ components:
capacity:
type: integer
nullable: true
- example: 150
+ example: 150000000000
tags:
type: array
items:
@@ -1118,13 +1153,13 @@ components:
example:
- id: "ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f"
zone: "madrid"
- capacity: 3
+ capacity: 300000000000
tags:
- fast
- amd64
- id: "4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff"
zone: "geneva"
- capacity: 7
+ capacity: 700000000000
tags:
- arm64
items:
@@ -1134,7 +1169,7 @@ components:
example:
- id: "e2ee7984ee65b260682086ec70026165903c86e601a4a5a501c1900afe28d84b"
zone: "geneva"
- capacity: 8
+ capacity: 800000000000
tags:
- gateway
- id: "4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff"