Skip to content
Aether Docs

List a cluster's persistent volumes

GET
/api/v1/organizations/{orgID}/clusters/{clusterID}/volumes
curl --request GET \
  --url https://api.aetherplatform.cloud/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/volumes \
  --header 'Authorization: Bearer <token>'

Read-only inventory of the cluster’s PersistentVolumes, read from the organization’s StorageInventory on the management cluster (nothing here calls the tenant cluster’s own apiserver, and there is no delete path — volume lifecycle stays a kubectl delete pvc inside the tenant).

Both byte figures are reported for every volume, and billed_on says which of the two is charged: aether-block volumes bill on provisioned_bytes (RBD space is reserved, so an empty claim costs what a full one does), aether-shared volumes bill on used_bytes (CephFS is thin-provisioned). used_percent is computed server-side and is not clamped — CephFS enforces its per-subvolume quota lazily, so a value above 100 is legitimate — and is 0 when there is no quota to divide by.

When the management read fails, the snapshot is stale or not Ready, or the cluster is not provisioned far enough to be identified, inventory_available is false and volumes is an empty array: “you have no volumes” and “we could not look” are different answers.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
orgID
required
string format: uuid

Organization UUID.

clusterID
required
string format: uuid

Cluster UUID.

Responses

Section titled “Responses”

200

Section titled “200”

The cluster’s volumes, plus the organization-wide shared-pool figures and the freshness of the underlying snapshot.

Media typeapplication/json
object
volumes
required
Array<object>
object
id
required

The CSI volume handle (block) or subvolume name (shared).

string
name
required

The volume’s display name.

string
type
required
string
Allowed values: block shared
storage_class
required
string
Allowed values: aether-block aether-shared
provisioned_bytes
required

The RBD image size for block volumes, or the subvolume’s quota for shared ones — where 0 means an INFINITE quota, not an empty volume.

integer format: int64
used_bytes
required
integer format: int64
used_percent
required

Used over provisioned, in percent. Unclamped (may exceed 100), and 0 when provisioned is 0.

number format: double
billed_on
required

Which of the two byte figures this volume is charged on.

string
Allowed values: provisioned used
state
required

The volume’s state as reported by the management cluster.

string
watchers
required

Open RBD watchers (0 means nothing has the image mapped).

integer
created_at
required
string format: date-time
org_shared_quota_bytes
required

The hard, OSD-enforced quota on the ORGANIZATION’s CephFS data pool, which every cluster in the org shares. 0 means unlimited/unset. Display only — nothing in billing reads it.

integer format: int64
org_shared_used_bytes
required

How much of that org-wide pool is occupied — not the sum of this cluster’s volumes.

integer format: int64
inventory_available
required

false when the management read failed or the snapshot is not provably current, in which case volumes is empty.

boolean
last_synced_at
required

When the organization’s inventory last completed a full sync. The zero time when inventory_available is false.

string format: date-time
Example
{
  "volumes": [
    {
      "type": "block",
      "storage_class": "aether-block",
      "billed_on": "provisioned"
    }
  ]
}

400

Section titled “400”

Malformed request — e.g. an invalid path UUID or an unparseable JSON body.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ]
  }
}

401

Section titled “401”

Missing or invalid credentials.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ]
  }
}

404

Section titled “404”

The requested resource was not found.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ]
  }
}