mirrors/garage
1
0
Fork 0
mirror of https://git.deuxfleurs.fr/Deuxfleurs/garage.git synced 2025-04-12 12:24:07 +00:00
Code Issues Projects Releases Packages Wiki Activity

admin api: small fixes and reordering

Browse source
This commit is contained in:
Alex Auvolat 2025-03-06 14:21:25 +01:00
parent 411f1d495c
commit 6b19d7628e
6 changed files with 106 additions and 76 deletions

2
doc/api/garage-admin-v0.html
View file

@ -1,7 +1,7 @@
<!DOCTYPE html>
<html>
<head>
<title>Garage Adminstration API v0</title>
<title>Garage adminstration API v0</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">

2
doc/api/garage-admin-v1.html
View file

@ -1,7 +1,7 @@
<!DOCTYPE html>
<html>
<head>
<title>Garage Adminstration API v0</title>
<title>Garage adminstration API v1</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">

2
doc/api/garage-admin-v2.html
View file

@ -1,7 +1,7 @@
<!DOCTYPE html>
<html>
<head>
<title>Garage Adminstration API v0</title>
<title>Garage adminstration API v2</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">

39
doc/api/garage-admin-v2.json
View file

@ -2,7 +2,7 @@
"openapi": "3.1.0",
"info": {
"title": "Garage administration API",
"description": "Administrate your Garage cluster programatically, including status, layout, keys, buckets, and maintainance tasks.\n\n*Disclaimer: This API may change in future Garage versions. Read the changelog and upgrade your scripts before upgrading. Additionnaly, this specification is very early stage and can contain bugs, especially on error return codes/types that are not tested yet. Do not expect a well finished and polished product!*",
"description": "Administrate your Garage cluster programatically, including status, layout, keys, buckets, and maintainance tasks.\n\n*Disclaimer: This API may change in future Garage versions. Read the changelog and upgrade your scripts before upgrading. Additionnaly, this specification is early stage and can contain bugs, so be careful and please report any issues on our issue tracker.*",
"contact": {
"name": "The Garage team",
"url": "https://garagehq.deuxfleurs.fr/",
@ -26,7 +26,7 @@
"tags": [
"Bucket alias"
],
"description": "Add an alias for the target bucket. This can be a local alias if `accessKeyId` is specified, or a global alias otherwise.",
"description": "Add an alias for the target bucket. This can be either a global or a local alias, depending on which fields are specified.",
"operationId": "AddBucketAlias",
"requestBody": {
"content": {
@ -493,7 +493,7 @@
"tags": [
"Cluster layout"
],
"description": "\nReturns the cluster's current layout, including:\n\n- Currently configured cluster layout\n- Staged changes to the cluster layout\n\n*Capacity is given in bytes*\n*The info returned by this endpoint is a subset of the info returned by `GET /GetClusterStatus`.*\n ",
"description": "\nReturns the cluster's current layout, including:\n\n- Currently configured cluster layout\n- Staged changes to the cluster layout\n\n*Capacity is given in bytes*\n ",
"operationId": "GetClusterLayout",
"responses": {
"200": {
@ -515,9 +515,9 @@
"/v2/GetClusterStatistics": {
"get": {
"tags": [
"Node"
"Cluster"
],
"description": "\nFetch global cluster statistics.\n ",
"description": "\nFetch global cluster statistics.\n\n*Note: do not try to parse the `freeform` field of the response, it is given as a string specifically because its format is not stable.*\n ",
"operationId": "GetClusterStatistics",
"responses": {
"200": {
@ -641,7 +641,7 @@
"tags": [
"Node"
],
"description": "\nFetch statistics for one or several Garage nodes.\n ",
"description": "\nFetch statistics for one or several Garage nodes.\n\n*Note: do not try to parse the `freeform` field of the response, it is given as a string specifically because its format is not stable.*\n ",
"operationId": "GetNodeStatistics",
"parameters": [
{
@ -791,7 +791,7 @@
"tags": [
"Node"
],
"description": "\nLaunch a repair operation on one or several cluster noes.\n ",
"description": "\nLaunch a repair operation on one or several cluster nodes.\n ",
"operationId": "LaunchRepairOperation",
"parameters": [
{
@ -997,7 +997,7 @@
"tags": [
"Bucket alias"
],
"description": "Remove an alias for the target bucket. This can be a local alias if `accessKeyId` is specified, or a global alias otherwise.",
"description": "Remove an alias for the target bucket. This can be either a global or a local alias, depending on which fields are specified.",
"operationId": "RemoveBucketAlias",
"requestBody": {
"content": {
@ -1073,7 +1073,7 @@
"tags": [
"Cluster layout"
],
"description": "Clear staged layout",
"description": "Clear staged layout changes",
"operationId": "RevertClusterLayout",
"responses": {
"200": {
@ -1598,10 +1598,12 @@
"type": [
"string",
"null"
]
],
"description": "An error message if Garage did not manage to connect to this node"
},
"success": {
"type": "boolean"
"type": "boolean",
"description": "`true` if Garage managed to connect to this node"
}
}
},
@ -1854,7 +1856,7 @@
},
"status": {
"type": "string",
"description": "One of `healthy`, `degraded` or `unavailable`:\n- healthy: Garage node is connected to all storage nodes\n- degraded: Garage node is not connected to all storage nodes, but a quorum of write nodes is available for all partitions\n- unavailable: a quorum of write nodes is not available for some partitions"
"description": "One of `healthy`, `degraded` or `unavailable`:\n- `healthy`: Garage node is connected to all storage nodes\n- `degraded`: Garage node is not connected to all storage nodes, but a quorum of write nodes is available for all partitions\n- `unavailable`: a quorum of write nodes is not available for some partitions"
},
"storageNodes": {
"type": "integer",
@ -2883,7 +2885,8 @@
],
"properties": {
"id": {
"type": "string"
"type": "string",
"description": "ID of the node for which this change applies"
}
}
}
@ -2898,7 +2901,8 @@
],
"properties": {
"remove": {
"type": "boolean"
"type": "boolean",
"description": "Set `remove` to `true` to remove the node from the layout"
}
}
},
@ -2915,16 +2919,19 @@
"null"
],
"format": "int64",
"description": "New capacity (in bytes) of the node",
"minimum": 0
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "New tags of the node"
},
"zone": {
"type": "string"
"type": "string",
"description": "New zone of the node"
}
}
}

55
src/api/admin/api.rs
View file

@ -46,7 +46,10 @@ admin_endpoints![
// Cluster operations
GetClusterStatus,
GetClusterHealth,
GetClusterStatistics,
ConnectClusterNodes,
// Layout operations
GetClusterLayout,
UpdateClusterLayout,
ApplyClusterLayout,
@ -78,9 +81,8 @@ admin_endpoints![
// Node operations
GetNodeInfo,
CreateMetadataSnapshot,
GetNodeStatistics,
GetClusterStatistics,
CreateMetadataSnapshot,
LaunchRepairOperation,
// Worker operations
@ -99,8 +101,8 @@ admin_endpoints![
local_admin_endpoints![
// Node operations
GetNodeInfo,
CreateMetadataSnapshot,
GetNodeStatistics,
CreateMetadataSnapshot,
LaunchRepairOperation,
// Background workers
ListWorkers,
@ -209,9 +211,9 @@ pub struct GetClusterHealthRequest;
#[serde(rename_all = "camelCase")]
pub struct GetClusterHealthResponse {
/// One of `healthy`, `degraded` or `unavailable`:
/// - healthy: Garage node is connected to all storage nodes
/// - degraded: Garage node is not connected to all storage nodes, but a quorum of write nodes is available for all partitions
/// - unavailable: a quorum of write nodes is not available for some partitions
/// - `healthy`: Garage node is connected to all storage nodes
/// - `degraded`: Garage node is not connected to all storage nodes, but a quorum of write nodes is available for all partitions
/// - `unavailable`: a quorum of write nodes is not available for some partitions
pub status: String,
/// the number of nodes this Garage node has had a TCP connection to since the daemon started
pub known_nodes: usize,
@ -229,6 +231,16 @@ pub struct GetClusterHealthResponse {
pub partitions_all_ok: usize,
}
// ---- GetClusterStatistics ----
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct GetClusterStatisticsRequest;
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct GetClusterStatisticsResponse {
pub freeform: String,
}
// ---- ConnectClusterNodes ----
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
@ -240,10 +252,16 @@ pub struct ConnectClusterNodesResponse(pub Vec<ConnectNodeResponse>);
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct ConnectNodeResponse {
/// `true` if Garage managed to connect to this node
pub success: bool,
/// An error message if Garage did not manage to connect to this node
pub error: Option<String>,
}
// **********************************************
// Layout operations
// **********************************************
// ---- GetClusterLayout ----
#[derive(Debug, Clone, Serialize, Deserialize)]
@ -260,6 +278,7 @@ pub struct GetClusterLayoutResponse {
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct NodeRoleChange {
/// ID of the node for which this change applies
pub id: String,
#[serde(flatten)]
pub action: NodeRoleChangeEnum,
@ -269,11 +288,17 @@ pub struct NodeRoleChange {
#[serde(untagged)]
pub enum NodeRoleChangeEnum {
#[serde(rename_all = "camelCase")]
Remove { remove: bool },
Remove {
/// Set `remove` to `true` to remove the node from the layout
remove: bool,
},
#[serde(rename_all = "camelCase")]
Update {
/// New zone of the node
zone: String,
/// New capacity (in bytes) of the node
capacity: Option<u64>,
/// New tags of the node
tags: Vec<String>,
},
}
@ -678,14 +703,6 @@ pub struct LocalGetNodeInfoResponse {
pub db_engine: String,
}
// ---- CreateMetadataSnapshot ----
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct LocalCreateMetadataSnapshotRequest;
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct LocalCreateMetadataSnapshotResponse;
// ---- GetNodeStatistics ----
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
@ -696,15 +713,13 @@ pub struct LocalGetNodeStatisticsResponse {
pub freeform: String,
}
// ---- GetClusterStatistics ----
// ---- CreateMetadataSnapshot ----
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct GetClusterStatisticsRequest;
pub struct LocalCreateMetadataSnapshotRequest;
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct GetClusterStatisticsResponse {
pub freeform: String,
}
pub struct LocalCreateMetadataSnapshotResponse;
// ---- LaunchRepairOperation ----

82
src/api/admin/openapi.rs
View file

@ -39,6 +39,21 @@ fn GetClusterStatus() -> () {}
)]
fn GetClusterHealth() -> () {}
#[utoipa::path(get,
path = "/v2/GetClusterStatistics",
tag = "Cluster",
description = "
Fetch global cluster statistics.
*Note: do not try to parse the `freeform` field of the response, it is given as a string specifically because its format is not stable.*
",
responses(
(status = 200, description = "Global cluster statistics", body = GetClusterStatisticsResponse),
(status = 500, description = "Internal server error")
),
)]
fn GetClusterStatistics() -> () {}
#[utoipa::path(post,
path = "/v2/ConnectClusterNodes",
tag = "Cluster",
@ -51,6 +66,10 @@ fn GetClusterHealth() -> () {}
)]
fn ConnectClusterNodes() -> () {}
// **********************************************
// Layout operations
// **********************************************
#[utoipa::path(get,
path = "/v2/GetClusterLayout",
tag = "Cluster layout",
@ -61,7 +80,6 @@ Returns the cluster's current layout, including:
- 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 /GetClusterStatus`.*
",
responses(
(status = 200, description = "Current cluster layout", body = GetClusterLayoutResponse),
@ -118,7 +136,7 @@ fn ApplyClusterLayout() -> () {}
#[utoipa::path(post,
path = "/v2/RevertClusterLayout",
tag = "Cluster layout",
description = "Clear staged layout",
description = "Clear staged layout changes",
responses(
(status = 200, description = "All pending changes to the cluster layout have been erased", body = RevertClusterLayoutResponse),
(status = 500, description = "Internal server error")
@ -389,7 +407,7 @@ fn DenyBucketKey() -> () {}
#[utoipa::path(post,
path = "/v2/AddBucketAlias",
tag = "Bucket alias",
description = "Add an alias for the target bucket. This can be a local alias if `accessKeyId` is specified, or a global alias otherwise.",
description = "Add an alias for the target bucket. This can be either a global or a local alias, depending on which fields are specified.",
request_body = AddBucketAliasRequest,
responses(
(status = 200, description = "Returns exhaustive information about the bucket", body = AddBucketAliasResponse),
@ -401,7 +419,7 @@ fn AddBucketAlias() -> () {}
#[utoipa::path(post,
path = "/v2/RemoveBucketAlias",
tag = "Bucket alias",
description = "Remove an alias for the target bucket. This can be a local alias if `accessKeyId` is specified, or a global alias otherwise.",
description = "Remove an alias for the target bucket. This can be either a global or a local alias, depending on which fields are specified.",
request_body = RemoveBucketAliasRequest,
responses(
(status = 200, description = "Returns exhaustive information about the bucket", body = RemoveBucketAliasResponse),
@ -430,6 +448,24 @@ Return information about the Garage daemon running on one or several nodes.
)]
fn GetNodeInfo() -> () {}
#[utoipa::path(get,
path = "/v2/GetNodeStatistics",
tag = "Node",
description = "
Fetch statistics for one or several Garage nodes.
*Note: do not try to parse the `freeform` field of the response, it is given as a string specifically because its format is not stable.*
",
params(
("node", description = "Node ID to query, or `*` for all nodes, or `self` for the node responding to the request"),
),
responses(
(status = 200, description = "Responses from individual cluster nodes", body = MultiResponse<LocalGetNodeStatisticsResponse>),
(status = 500, description = "Internal server error")
),
)]
fn GetNodeStatistics() -> () {}
#[utoipa::path(post,
path = "/v2/CreateMetadataSnapshot",
tag = "Node",
@ -446,40 +482,11 @@ Instruct one or several nodes to take a snapshot of their metadata databases.
)]
fn CreateMetadataSnapshot() -> () {}
#[utoipa::path(get,
path = "/v2/GetNodeStatistics",
tag = "Node",
description = "
Fetch statistics for one or several Garage nodes.
",
params(
("node", description = "Node ID to query, or `*` for all nodes, or `self` for the node responding to the request"),
),
responses(
(status = 200, description = "Responses from individual cluster nodes", body = MultiResponse<LocalGetNodeStatisticsResponse>),
(status = 500, description = "Internal server error")
),
)]
fn GetNodeStatistics() -> () {}
#[utoipa::path(get,
path = "/v2/GetClusterStatistics",
tag = "Node",
description = "
Fetch global cluster statistics.
",
responses(
(status = 200, description = "Global cluster statistics", body = GetClusterStatisticsResponse),
(status = 500, description = "Internal server error")
),
)]
fn GetClusterStatistics() -> () {}
#[utoipa::path(post,
path = "/v2/LaunchRepairOperation",
tag = "Node",
description = "
Launch a repair operation on one or several cluster noes.
Launch a repair operation on one or several cluster nodes.
",
params(
("node", description = "Node ID to query, or `*` for all nodes, or `self` for the node responding to the request"),
@ -661,7 +668,7 @@ impl Modify for SecurityAddon {
title = "Garage administration API",
description = "Administrate your Garage cluster programatically, including status, layout, keys, buckets, and maintainance tasks.
*Disclaimer: This API may change in future Garage versions. Read the changelog and upgrade your scripts before upgrading. Additionnaly, this specification is very early stage and can contain bugs, especially on error return codes/types that are not tested yet. Do not expect a well finished and polished product!*",
*Disclaimer: This API may change in future Garage versions. Read the changelog and upgrade your scripts before upgrading. Additionnaly, this specification is early stage and can contain bugs, so be careful and please report any issues on our issue tracker.*",
contact(
name = "The Garage team",
email = "garagehq@deuxfleurs.fr",
@ -674,7 +681,9 @@ impl Modify for SecurityAddon {
// Cluster operations
GetClusterHealth,
GetClusterStatus,
GetClusterStatistics,
ConnectClusterNodes,
// Layout operations
GetClusterLayout,
UpdateClusterLayout,
ApplyClusterLayout,
@ -701,9 +710,8 @@ impl Modify for SecurityAddon {
RemoveBucketAlias,
// Node operations
GetNodeInfo,
CreateMetadataSnapshot,
GetNodeStatistics,
GetClusterStatistics,
CreateMetadataSnapshot,
LaunchRepairOperation,
// Worker operations
ListWorkers,