Volumes HTTP API

The /volume endpoints are used to query for and interact with volumes.

List Volumes

This endpoint lists all volumes.

Method	Path	Produces
`GET`	`/v1/volumes`	`application/json`

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

Blocking Queries	ACL Required
`YES`	`namespace:csi-list-volume`

Parameters

type (string: "")- Specifies the type of volume to query. Currently only supports csi. This is specified as a query string parameter. Returns an empty list if omitted.
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). This is specified 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). This is specified as a query string parameter.

Sample Request

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

Sample Response

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

Read Volume

This endpoint reads information about a specific volume.

Method	Path	Produces
`GET`	`/v1/volume/csi/:volume_id`	`application/json`

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

Blocking Queries	ACL Required
`YES`	`namespace:csi-read-volume`

Parameters

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

Sample Request

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

Sample Response

{  "ID": "volume-id1",  "Name": "volume id1",  "Namespace": "default",  "ExternalID": "volume-id1",  "Topologies": [{ "foo": "bar" }],  "AccessMode": "multi-node-single-writer",  "AttachmentMode": "file-system",  "Allocations": [    {      "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",      "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",      "Name": "example.cache[0]",      "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",      "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",      "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",      "RescheduleTracker": {        "Events": [          {            "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",            "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",            "RescheduleTime": 1517434161192946200,            "Delay": "5000000000"          }        ]      },      "JobID": "example",      "TaskGroup": "cache",      "DesiredStatus": "run",      "DesiredDescription": "",      "ClientStatus": "running",      "ClientDescription": "",      "TaskStates": {        "redis": {          "State": "running",          "FinishedAt": "0001-01-01T00:00:00Z",          "LastRestart": "0001-01-01T00:00:00Z",          "Restarts": 0,          "StartedAt": "2017-07-25T23:36:26.106431265Z",          "Failed": false,          "Events": [            {              "Type": "Received",              "Time": 1495747371795703800,              "FailsTask": false,              "RestartReason": "",              "SetupError": "",              "DriverError": "",              "ExitCode": 0,              "Signal": 0,              "Message": "",              "KillTimeout": 0,              "KillError": "",              "KillReason": "",              "StartDelay": 0,              "DownloadError": "",              "ValidationError": "",              "DiskLimit": 0,              "FailedSibling": "",              "VaultError": "",              "TaskSignalReason": "",              "TaskSignal": "",              "DriverMessage": ""            },            {              "Type": "Driver",              "Time": 1495747371798867200,              "FailsTask": false,              "RestartReason": "",              "SetupError": "",              "DriverError": "",              "ExitCode": 0,              "Signal": 0,              "Message": "",              "KillTimeout": 0,              "KillError": "",              "KillReason": "",              "StartDelay": 0,              "DownloadError": "",              "ValidationError": "",              "DiskLimit": 0,              "FailedSibling": "",              "VaultError": "",              "TaskSignalReason": "",              "TaskSignal": "",              "DriverMessage": "Downloading image redis:3.2"            },            {              "Type": "Started",              "Time": 1495747379525667800,              "FailsTask": false,              "RestartReason": "",              "SetupError": "",              "DriverError": "",              "ExitCode": 0,              "Signal": 0,              "Message": "",              "KillTimeout": 0,              "KillError": "",              "KillReason": "",              "StartDelay": 0,              "DownloadError": "",              "ValidationError": "",              "DiskLimit": 0,              "FailedSibling": "",              "VaultError": "",              "TaskSignalReason": "",              "TaskSignal": "",              "DriverMessage": ""            }          ]        }      },      "CreateIndex": 54,      "ModifyIndex": 57,      "CreateTime": 1495747371794276400,      "ModifyTime": 1495747371794276400    }  ],  "Schedulable": true,  "PluginID": "plugin-id1",  "Provider": "ebs",  "Version": "1.0.1",  "ControllerRequired": true,  "ControllersHealthy": 3,  "ControllersExpected": 3,  "NodesHealthy": 15,  "NodesExpected": 18,  "ResourceExhausted": 0,  "CreateIndex": 42,  "ModifyIndex": 64}

Register Volume

This endpoint registers an external volume with Nomad. It is an error to register an existing volume.

Method	Path	Produces
`PUT`	`/v1/volume/csi/:volume_id`	`application/json`

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

Blocking Queries	ACL Required
`NO`	`namespace:csi-write-volume`

Parameters

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

Sample Payload

The payload must include a JSON document that described the volume's parameters.

{  "ID": "volume-id1",  "Name": "volume id1",  "Namespace": "default",  "ExternalID": "volume-id1",  "Topologies": [{ "foo": "bar" }],  "AccessMode": "multi-node-single-writer",  "AttachmentMode": "file-system",  "PluginID": "plugin-id1"}

Sample Request

$ curl \    --request PUT \    --data @payload.json \    https://localhost:4646/v1/volume/csi/volume-id1

Delete Volume

This endpoint deregisters an external volume with Nomad. It is an error to deregister a volume that is in use.

Method	Path	Produces
`DELTE`	`/v1/volume/csi/:volume_id`	`application/json`

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

Blocking Queries	ACL Required
`NO`	`namespace:csi-write-volume`

Parameters

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

Sample Request

$ curl \    --request DELETE \    --data @payload.json \    https://localhost:4646/v1/volume/csi/volume-id1