Volumes HTTP API

The /volume and /volumes endpoints query for and interact with Container Storage Interface (CSI) volumes and dynamic host volumes.

List Volumes

This endpoint lists all volumes.

The following table shows this endpoint's support for blocking queries and required ACLs.

Parameters

• type (string: <required>) - Specifies the type of volume to query. One of csi or host. The host value queries dynamic host volumes. Specify this as a query string parameter.

• node_id (string: "") - Specifies a string to filter volumes based on an Node ID prefix. Because the value is decoded to bytes, the prefix must have an even number of hexadecimal characters (0-9a-f). Specify this as a query string parameter.

• plugin_id (string: "") - Specifies a string to filter volumes based on a plugin ID prefix. Because the value is decoded to bytes, the prefix must have an even number of hexadecimal characters (0-9a-f). Specify this as a query string parameter.

• next_token (string: "") - This endpoint supports paging. The next_token parameter accepts a string which identifies the next expected volume. This value can be obtained from the X-Nomad-NextToken header from the previous response.

• per_page (int: 0) - Specifies a maximum number of volumes to return for this request. If omitted, the response is not paginated. The value of the X-Nomad-NextToken header of the last response can be used as the next_token of the next request to fetch additional pages.

• filter (string: "") - Specifies the expression used to filter the results. Consider using pagination or a query parameter to reduce resource used to serve the request.

Sample Request

$ curl \
    https://localhost:4646/v1/volumes?type=csi&node_id=foo&plugin_id=plugin-id1

Sample Response for CSI Volumes

[
  {
    "ID": "volume-id1",
    "ExternalID": "vol-abcdef",
    "Namespace": "default",
    "Name": "volume id1",
    "Topologies": [
      {
        "foo": "bar"
      }
    ],
    "AccessMode": "multi-node-single-writer",
    "AttachmentMode": "file-system",
    "CurrentReaders": 2,
    "CurrentWriters": 1,
    "Schedulable": true,
    "PluginID": "plugin-id1",
    "Provider": "ebs",
    "ControllerRequired": true,
    "ControllersHealthy": 3,
    "ControllersExpected": 3,
    "NodesHealthy": 15,
    "NodesExpected": 18,
    "ResourceExhausted": 0,
    "CreateIndex": 42,
    "ModifyIndex": 64
  }
]

Sample Response for dynamic host volumes

[
  {
    "CapacityBytes": 1048576000,
    "CreateIndex": 42,
    "CreateTime": 1736191825846395400,
    "ID": "3735cc2c-cc64-11ef-89ed-bfb5b3bc38ea",
    "ModifyIndex": 64,
    "ModifyTime": 1736191825846395400,
    "Name": "example",
    "Namespace": "default",
    "NodeID": "5c5830d0-cc64-11ef-a293-4f03e55969ea",
    "NodePool": "default",
    "PluginID": "plugin-id1",
    "State": "ready"
  }
]

Read CSI Volume

This endpoint reads information about a specific CSI volume.

The following table shows this endpoint's support for blocking queries and required ACLs.

Parameters

• :volume_id (string: <required>) - Specifies the ID of the volume. This must be the full ID. Specify this as part of the path.

Sample Request

$ curl \
    https://localhost:4646/v1/volume/csi/volume-id1

Sample Response

{
  "ID": "volume-id1",
  "Name": "volume id1",