diff options
| -rw-r--r-- | doc/drafts/admin-api.md | 79 | ||||
| -rw-r--r-- | src/api/admin/cluster.rs | 2 |
2 files changed, 78 insertions, 3 deletions
diff --git a/doc/drafts/admin-api.md b/doc/drafts/admin-api.md index 1ba868ef..a518c93f 100644 --- a/doc/drafts/admin-api.md +++ b/doc/drafts/admin-api.md @@ -7,11 +7,15 @@ The admin API uses two different tokens for acces control, that are specified in # Administration API endpoints -## Metrics `GET /metrics` +## Metrics-related endpoints + +### Metrics `GET /metrics` Returns internal Garage metrics in Prometheus format. -## GetClusterStatus `GET /status` +## Cluster operations + +### GetClusterStatus `GET /status` Returns the cluster's current status in JSON, including: @@ -50,6 +54,7 @@ Example response body: } }, "layout": { + "version": 12, "roles": { "ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f": { "zone": "dc1", @@ -86,7 +91,7 @@ Example response body: } ``` -## GetClusterLayout `GET /layout` +### GetClusterLayout `GET /layout` Returns the cluster's current layout in JSON, including: @@ -99,6 +104,7 @@ Example response body: ```json { + "version": 12, "roles": { "ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f": { "zone": "dc1", @@ -133,3 +139,70 @@ Example response body: } } ``` + +### UpdateClusterLayout `POST /layout` + +Send modifications to the cluster layout. These modifications will +be included in the staged role changes, visible in subsequent calls +of `GetClusterLayout`. Once the set of staged changes is satisfactory, +the user may call `ApplyClusterLayout` to apply the changed changes, +or `Revert ClusterLayout` to clear all of the staged changes in +the layout. + +Request body format: + +```json +{ + <node_id>: { + "capacity": <new_capacity>, + "zone": <new_zone>, + "tags": [ + <new_tag>, + ... + ] + }, + <node_id_to_remove>: null, + ... +} +``` + +Contrary to the CLI that may update only a subset of the fields +`capacity`, `zone` and `tags`, when calling this API all of these +values must be specified. + + +### ApplyClusterLayout `POST /layout/apply` + +Applies to the cluster the layout changes currently registered as +staged layout changes. + +Request body format: + +```json +{ + "version": 13 +} +``` + +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. + +### RevertClusterLayout `POST /layout/revert` + +Clears all of the staged layout changes. + +Request body format: + +```json +{ + "version": 13 +} +``` + +Reverting the staged changes is done by incrementing the version number +and clearing the contents of the staged change list. +Similarly to the CLI, the body must include the incremented +version number, which MUST be 1 + the value of the currently +existing layout in the cluster. + diff --git a/src/api/admin/cluster.rs b/src/api/admin/cluster.rs index f4835648..0eb754ac 100644 --- a/src/api/admin/cluster.rs +++ b/src/api/admin/cluster.rs @@ -52,6 +52,7 @@ fn get_cluster_layout(garage: &Arc<Garage>) -> GetClusterLayoutResponse { let layout = garage.system.get_cluster_layout(); GetClusterLayoutResponse { + version: layout.version, roles: layout .roles .items() @@ -78,6 +79,7 @@ struct GetClusterStatusResponse { #[derive(Serialize)] struct GetClusterLayoutResponse { + version: u64, roles: HashMap<String, Option<NodeRole>>, #[serde(rename = "stagedRoleChanges")] staged_role_changes: HashMap<String, Option<NodeRole>>, |