Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deuxfleurs-org/garage/llms.txt

Use this file to discover all available pages before exploring further.

Cluster management endpoints allow you to monitor and configure your Garage cluster’s status, health, and layout configuration.

​
Get Cluster Status

Returns the cluster’s current status, including node information and layout details. 
GET /v2/GetClusterStatus

​
Response

​
layoutVersion
integer
required
Current version number of the cluster layout
​
nodes
array
required
List of nodes in the cluster

​
Example

curl -H 'Authorization: Bearer s3cr3t' \
  http://localhost:3903/v2/GetClusterStatus | jq

{
  "layoutVersion": 12,
  "nodes": [
    {
      "id": "62b218d848e86a84f0ec5cae0458a974d9993d87b90c2c28",
      "garageVersion": "v2.0.0",
      "addr": "10.0.0.11:3901",
      "hostname": "node1.garage.local",
      "isUp": true,
      "lastSeenSecsAgo": 2,
      "role": {
        "zone": "dc1",
        "capacity": 100000000000,
        "tags": ["fast"]
      },
      "dataPartition": {
        "available": 75000000000,
        "total": 100000000000
      }
    }
  ]
}

​
Get Cluster Health

Returns the cluster’s health status with partition and node connectivity information. 
GET /v2/GetClusterHealth

​
Response

​
status
string
required
Overall cluster status: healthy, degraded, or unavailable
  • healthy: Connected to all storage nodes
  • degraded: Not connected to all nodes, but write quorum available
  • unavailable: Write quorum not available for some partitions
​
knownNodes
integer
required
Number of nodes this node has connected to since daemon start
​
connectedNodes
integer
required
Number of nodes currently connected
​
storageNodes
integer
required
Number of storage nodes registered in cluster layout
​
storageNodesUp
integer
required
Number of storage nodes currently connected
​
partitions
integer
required
Total number of partitions (currently always 256)
​
partitionsQuorum
integer
required
Number of partitions with write quorum available
​
partitionsAllOk
integer
required
Number of partitions with all storage nodes connected

​
Example

curl -H 'Authorization: Bearer s3cr3t' \
  http://localhost:3903/v2/GetClusterHealth | jq

{
  "status": "healthy",
  "knownNodes": 3,
  "connectedNodes": 3,
  "storageNodes": 3,
  "storageNodesUp": 3,
  "partitions": 256,
  "partitionsQuorum": 256,
  "partitionsAllOk": 256
}

​
Get Cluster Statistics

Returns global cluster statistics including storage usage and capacity. 
GET /v2/GetClusterStatistics

​
Response

​
freeform
string
required
Plain-text formatted statistics. Do not parse this field as its format is not stable.

​
Example

curl -H 'Authorization: Bearer s3cr3t' \
  http://localhost:3903/v2/GetClusterStatistics

​
Get Cluster Layout

Returns the cluster’s current layout configuration, including staged changes. 
GET /v2/GetClusterLayout

​
Response

​
version
integer
required
Current version number of the cluster layout
​
roles
array
required
List of nodes with roles in the current layout
​
stagedRoleChanges
array
required
List of pending role changes that will be applied on next layout update
​
partitionSize
integer
required
Size of one partition in bytes
​
parameters
object
required
Layout computation parameters

​
Example

curl -H 'Authorization: Bearer s3cr3t' \
  http://localhost:3903/v2/GetClusterLayout | jq

​
Update Cluster Layout

Send modifications to the cluster layout. Changes are staged and must be applied with ApplyClusterLayout. 
POST /v2/UpdateClusterLayout

​
Request Body

​
nodeId
string
required
ID of the node to configure
​
zone
string
Availability zone for the node
​
capacity
integer
Storage capacity in bytes. Set to null to configure as gateway node.Example: 100000000000 for 100GB (SI units: 1kB = 1000 bytes)
​
tags
array
Tags for the node
​
remove
boolean
Set to true to remove the node from the layout

​
Example: Add Storage Node

curl -X POST -H 'Authorization: Bearer s3cr3t' \
  -H 'Content-Type: application/json' \
  -d '{
    "62b218d848e86a84f0ec5cae0458a974d9993d87b90c2c28": {
      "zone": "dc1",
      "capacity": 100000000000,
      "tags": ["fast", "ssd"]
    }
  }' \
  http://localhost:3903/v2/UpdateClusterLayout

​
Example: Configure Gateway Node

curl -X POST -H 'Authorization: Bearer s3cr3t' \
  -H 'Content-Type: application/json' \
  -d '{
    "62b218d848e86a84f0ec5cae0458a974d9993d87b90c2c28": {
      "zone": "dc1",
      "capacity": null,
      "tags": ["gateway"]
    }
  }' \
  http://localhost:3903/v2/UpdateClusterLayout

​
Apply Cluster Layout

Applies staged layout changes to the cluster. 
POST /v2/ApplyClusterLayout

​
Request Body

​
version
integer
required
Expected new version number (safety measure to prevent concurrent modifications)

​
Response

​
layout
object
required
The newly applied cluster layout
​
message
array
required
Plain-text information about the layout computation (do not parse)

​
Example

curl -X POST -H 'Authorization: Bearer s3cr3t' \
  -H 'Content-Type: application/json' \
  -d '{"version": 13}' \
  http://localhost:3903/v2/ApplyClusterLayout

​
Revert Cluster Layout

Clears all staged layout changes without applying them. 
POST /v2/RevertClusterLayout

​
Example

curl -X POST -H 'Authorization: Bearer s3cr3t' \
  http://localhost:3903/v2/RevertClusterLayout

​
Connect Cluster Nodes

Instructs this node to connect to other Garage nodes. 
POST /v2/ConnectClusterNodes

​
Request Body

Array of node addresses in format <node_id>@<address>:<port>
​
nodes
array
required
List of node connection strings

​
Response

​
results
array
required
Connection results for each node

​
Example

curl -X POST -H 'Authorization: Bearer s3cr3t' \
  -H 'Content-Type: application/json' \
  -d '[
    "62b218d848e86a84f0ec5cae0458a974d9993d87b90c2c28@10.0.0.11:3901",
    "a11c7cf18af297379c0c6f5d7b8f8d2e9f3e1b4c5d6a7b8c@10.0.0.12:3901"
  ]' \
  http://localhost:3903/v2/ConnectClusterNodes

[
  {
    "success": true,
    "error": null
  },
  {
    "success": false,
    "error": "Connection timeout"
  }
]