mirror of
https://github.com/deuxfleurs-org/garage.git
synced 2026-08-29 16:37:09 +00:00
admin api: small refactor + add comments to layout-related calls
This commit is contained in:
Alex Auvolat
@@ -1412,6 +1412,7 @@
|
||||
"version": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "As a safety measure, the new version number of the layout must\nbe specified here",
|
||||
"minimum": 0
|
||||
}
|
||||
}
|
||||
@@ -1424,13 +1425,15 @@
|
||||
],
|
||||
"properties": {
|
||||
"layout": {
|
||||
"$ref": "#/components/schemas/GetClusterLayoutResponse"
|
||||
"$ref": "#/components/schemas/GetClusterLayoutResponse",
|
||||
"description": "Details about the new cluster layout"
|
||||
},
|
||||
"message": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"description": "Plain-text information about the layout computation\n(do not try to parse this)"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -1666,11 +1669,13 @@
|
||||
],
|
||||
"properties": {
|
||||
"allowMissingData": {
|
||||
"type": "boolean"
|
||||
"type": "boolean",
|
||||
"description": "Allow the skip even if a quorum of nodes could not be found for\nthe data among the remaining nodes"
|
||||
},
|
||||
"version": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "Version number of the layout to assume is currently up-to-date.\nThis will generally be the current layout version.",
|
||||
"minimum": 0
|
||||
}
|
||||
}
|
||||
@@ -1686,13 +1691,15 @@
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"description": "Nodes for which the ACK update tracker has been updated to `version`"
|
||||
},
|
||||
"syncUpdated": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"description": "If `allow_missing_data` is set,\nnodes for which the SYNC update tracker has been updated to `version`"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -1708,19 +1715,23 @@
|
||||
"gatewayNodes": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "Number of nodes with a gateway role in this layout version",
|
||||
"minimum": 0
|
||||
},
|
||||
"status": {
|
||||
"$ref": "#/components/schemas/ClusterLayoutVersionStatus"
|
||||
"$ref": "#/components/schemas/ClusterLayoutVersionStatus",
|
||||
"description": "Status of this layout version"
|
||||
},
|
||||
"storageNodes": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "Number of nodes with an assigned storage capacity in this layout version",
|
||||
"minimum": 0
|
||||
},
|
||||
"version": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "Version number of this layout version",
|
||||
"minimum": 0
|
||||
}
|
||||
}
|
||||
@@ -1836,11 +1847,13 @@
|
||||
"available": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "Number of bytes available",
|
||||
"minimum": 0
|
||||
},
|
||||
"total": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "Total number of bytes",
|
||||
"minimum": 0
|
||||
}
|
||||
}
|
||||
@@ -2038,11 +2051,13 @@
|
||||
"currentVersion": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "The current version number of the cluster layout",
|
||||
"minimum": 0
|
||||
},
|
||||
"minAck": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "All nodes in the cluster are aware of layout versions up to\nthis version number (at least)",
|
||||
"minimum": 0
|
||||
},
|
||||
"updateTrackers": {
|
||||
@@ -2050,6 +2065,7 @@
|
||||
"object",
|
||||
"null"
|
||||
],
|
||||
"description": "Detailed update trackers for nodes (see\n`https://garagehq.deuxfleurs.fr/blog/2023-12-preserving-read-after-write-consistency/`)",
|
||||
"additionalProperties": {
|
||||
"$ref": "#/components/schemas/NodeUpdateTrackers"
|
||||
},
|
||||
@@ -2061,7 +2077,8 @@
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/ClusterLayoutVersion"
|
||||
}
|
||||
},
|
||||
"description": "Layout version history"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -2070,24 +2087,27 @@
|
||||
"required": [
|
||||
"version",
|
||||
"roles",
|
||||
"partitionSize",
|
||||
"parameters",
|
||||
"partitionSize",
|
||||
"stagedRoleChanges"
|
||||
],
|
||||
"properties": {
|
||||
"parameters": {
|
||||
"$ref": "#/components/schemas/LayoutParameters"
|
||||
"$ref": "#/components/schemas/LayoutParameters",
|
||||
"description": "Layout parameters used when the current layout was computed"
|
||||
},
|
||||
"partitionSize": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "The size, in bytes, of one Garage partition (= a shard)",
|
||||
"minimum": 0
|
||||
},
|
||||
"roles": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/LayoutNodeRole"
|
||||
}
|
||||
},
|
||||
"description": "List of nodes that currently have a role in the cluster layout"
|
||||
},
|
||||
"stagedParameters": {
|
||||
"oneOf": [
|
||||
@@ -2095,7 +2115,8 @@
|
||||
"type": "null"
|
||||
},
|
||||
{
|
||||
"$ref": "#/components/schemas/LayoutParameters"
|
||||
"$ref": "#/components/schemas/LayoutParameters",
|
||||
"description": "Layout parameters to use when computing the next version of\nthe cluster layout"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -2103,11 +2124,13 @@
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/NodeRoleChange"
|
||||
}
|
||||
},
|
||||
"description": "List of nodes that will have a new role or whose role will be\nremoved in the next version of the cluster layout"
|
||||
},
|
||||
"version": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "The current version number of the cluster layout",
|
||||
"minimum": 0
|
||||
}
|
||||
}
|
||||
@@ -2133,13 +2156,15 @@
|
||||
"layoutVersion": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"description": "Current version number of the cluster layout",
|
||||
"minimum": 0
|
||||
},
|
||||
"nodes": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/NodeResp"
|
||||
}
|
||||
},
|
||||
"description": "List of nodes that are either currently connected, part of the\ncurrent cluster layout, or part of an older cluster layout that\nis still active in the cluster (being drained)."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -2250,16 +2275,28 @@
|
||||
"null"
|
||||
],
|
||||
"format": "int64",
|
||||
"description": "Capacity (in bytes) assigned by the cluster administrator,\nabsent for gateway nodes",
|
||||
"minimum": 0
|
||||
},
|
||||
"id": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"description": "Identifier of the node"
|
||||
},
|
||||
"storedPartitions": {
|
||||
"type": [
|
||||
"integer",
|
||||
"null"
|
||||
],
|
||||
"format": "int64",
|
||||
"description": "Number of partitions stored on this node\n(a result of the layout computation)",
|
||||
"minimum": 0
|
||||
},
|
||||
"tags": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"description": "List of tags assigned by the cluster administrator"
|
||||
},
|
||||
"usableCapacity": {
|
||||
"type": [
|
||||
@@ -2267,10 +2304,12 @@
|
||||
"null"
|
||||
],
|
||||
"format": "int64",
|
||||
"description": "Capacity (in bytes) that is actually usable on this node in the current\nlayout, which is equal to `stored_partitions` × `partition_size`",
|
||||
"minimum": 0
|
||||
},
|
||||
"zone": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"description": "Zone name assigned by the cluster administrator"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -2281,7 +2320,8 @@
|
||||
],
|
||||
"properties": {
|
||||
"zoneRedundancy": {
|
||||
"$ref": "#/components/schemas/ZoneRedundancy"
|
||||
"$ref": "#/components/schemas/ZoneRedundancy",
|
||||
"description": "Minimum number of zones in which a data partition must be replicated"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -3071,7 +3111,6 @@
|
||||
"NodeAssignedRole": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"zone",
|
||||
"tags"
|
||||
],
|
||||
@@ -3082,19 +3121,19 @@
|
||||
"null"
|
||||
],
|
||||
"format": "int64",
|
||||
"description": "Capacity (in bytes) assigned by the cluster administrator,\nabsent for gateway nodes",
|
||||
"minimum": 0
|
||||
},
|
||||
"id": {
|
||||
"type": "string"
|
||||
},
|
||||
"tags": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"description": "List of tags assigned by the cluster administrator"
|
||||
},
|
||||
"zone": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"description": "Zone name assigned by the cluster administrator"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -3110,7 +3149,8 @@
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
],
|
||||
"description": "Socket address used by other nodes to connect to this node for RPC"
|
||||
},
|
||||
"dataPartition": {
|
||||
"oneOf": [
|
||||
@@ -3118,24 +3158,29 @@
|
||||
"type": "null"
|
||||
},
|
||||
{
|
||||
"$ref": "#/components/schemas/FreeSpaceResp"
|
||||
"$ref": "#/components/schemas/FreeSpaceResp",
|
||||
"description": "Total and available space on the disk partition(s) containing the data\ndirectory(ies)"
|
||||
}
|
||||
]
|
||||
},
|
||||
"draining": {
|
||||
"type": "boolean"
|
||||
"type": "boolean",
|
||||
"description": "Whether this node is part of an older layout version and is draining data."
|
||||
},
|
||||
"hostname": {
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
],
|
||||
"description": "Hostname of the node"
|
||||
},
|
||||
"id": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"description": "Full-length node identifier"
|
||||
},
|
||||
"isUp": {
|
||||
"type": "boolean"
|
||||
"type": "boolean",
|
||||
"description": "Whether this node is connected in the cluster"
|
||||
},
|
||||
"lastSeenSecsAgo": {
|
||||
"type": [
|
||||
@@ -3143,6 +3188,7 @@
|
||||
"null"
|
||||
],
|
||||
"format": "int64",
|
||||
"description": "For disconnected nodes, the number of seconds since last contact,\nor `null` if no contact was established since Garage restarted.",
|
||||
"minimum": 0
|
||||
},
|
||||
"metadataPartition": {
|
||||
@@ -3151,7 +3197,8 @@
|
||||
"type": "null"
|
||||
},
|
||||
{
|
||||
"$ref": "#/components/schemas/FreeSpaceResp"
|
||||
"$ref": "#/components/schemas/FreeSpaceResp",
|
||||
"description": "Total and available space on the disk partition containing the\nmetadata directory"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -3161,7 +3208,8 @@
|
||||
"type": "null"
|
||||
},
|
||||
{
|
||||
"$ref": "#/components/schemas/NodeAssignedRole"
|
||||
"$ref": "#/components/schemas/NodeAssignedRole",
|
||||
"description": "Role assigned to this node in the current cluster layout"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -3201,33 +3249,7 @@
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"required": [
|
||||
"zone",
|
||||
"tags"
|
||||
],
|
||||
"properties": {
|
||||
"capacity": {
|
||||
"type": [
|
||||
"integer",
|
||||
"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",
|
||||
"description": "New zone of the node"
|
||||
}
|
||||
}
|
||||
"$ref": "#/components/schemas/NodeAssignedRole"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -3265,7 +3287,8 @@
|
||||
],
|
||||
"properties": {
|
||||
"error": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"description": "Error message indicating that the layout could not be computed\nwith the provided configuration"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -3280,10 +3303,12 @@
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"description": "Plain-text information about the layout computation\n(do not try to parse this)"
|
||||
},
|
||||
"newLayout": {
|
||||
"$ref": "#/components/schemas/GetClusterLayoutResponse"
|
||||
"$ref": "#/components/schemas/GetClusterLayoutResponse",
|
||||
"description": "Details about the new cluster layout"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -3439,7 +3464,8 @@
|
||||
"type": "null"
|
||||
},
|
||||
{
|
||||
"$ref": "#/components/schemas/LayoutParameters"
|
||||
"$ref": "#/components/schemas/LayoutParameters",
|
||||
"description": "New layout computation parameters to use"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -3447,7 +3473,8 @@
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/NodeRoleChange"
|
||||
}
|
||||
},
|
||||
"description": "New node roles to assign or remove in the cluster layout"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -3631,18 +3658,21 @@
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "object",
|
||||
"description": "Partitions must be replicated in at least this number of\ndistinct zones.",
|
||||
"required": [
|
||||
"atLeast"
|
||||
],
|
||||
"properties": {
|
||||
"atLeast": {
|
||||
"type": "integer",
|
||||
"description": "Partitions must be replicated in at least this number of\ndistinct zones.",
|
||||
"minimum": 0
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "Partitions must be replicated in as many zones as possible:\nas many zones as there are replicas, if there are enough distinct\nzones, or at least one in each zone otherwise.",
|
||||
"enum": [
|
||||
"maximum"
|
||||
]
|
||||
|
||||
Reference in New Issue
Block a user