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
    }
  ],
  "ReadAllocs": {
    "a8198d79-cfdb-6593-a999-1e9adabcba2e": null
  },
  "WriteAllocs": {},
  "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.

{
  "Volumes": [
    {
      "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
`DELETE`	`/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.
force (bool: false)- Force deregistration of the volume and immediately drop claims for terminal allocations. Returns an error if the volume has running allocations. This does not detach the volume from client nodes. This is specified as a query string parameter.

Sample Request

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

Detach Volume

This endpoint detaches an external volume from a Nomad client node. It is an error to detach a volume that is in use.

Method	Path	Produces
`DELETE`	`/v1/volume/csi/:volume_id/detach`	`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.
node (string: <required>)- The node to detach the volume from. This is specified as a query string parameter.

Sample Request

$ curl \
    --request DELETE \
    https://localhost:4646/v1/volume/csi/volume-id/detach?node=00000000-0000-0000-0000-000000000000