1---
2layout: api
3page_title: Volumes - HTTP API
4description: The `/volume` endpoints are used to query for and interact with volumes.
5---
6
7# Volumes HTTP API
8
9The `/volume` and `/volumes` endpoints are used to query for and interact with
10volumes.
11
12## List Volumes
13
14This endpoint lists all volumes.
15
16| Method | Path          | Produces           |
17| ------ | ------------- | ------------------ |
18| `GET`  | `/v1/volumes` | `application/json` |
19
20The table below shows this endpoint's support for
21[blocking queries](/api-docs#blocking-queries) and
22[required ACLs](/api-docs#acls).
23
24| Blocking Queries | ACL Required                |
25| ---------------- | --------------------------- |
26| `YES`            | `namespace:csi-list-volume` |
27
28### Parameters
29
30- `type` `(string: "")` - Specifies the type of volume to
31  query. Currently only supports `csi`. This is specified as a query
32  string parameter. Returns an empty list if omitted.
33
34- `node_id` `(string: "")` - Specifies a string to filter volumes
35  based on an Node ID prefix. Because the value is decoded to bytes,
36  the prefix must have an even number of hexadecimal characters
37  (0-9a-f). This is specified as a query string parameter.
38
39- `plugin_id` `(string: "")` - Specifies a string to filter volumes
40  based on a plugin ID prefix. Because the value is decoded to bytes,
41  the prefix must have an even number of hexadecimal characters
42  (0-9a-f). This is specified as a query string parameter.
43
44### Sample Request
45
46```shell-session
47$ curl \
48    https://localhost:4646/v1/volumes?type=csi&node_id=foo&plugin_id=plugin-id1
49```
50
51### Sample Response
52
53```json
54[
55  {
56    "ID": "volume-id1",
57    "ExternalID": "vol-abcdef",
58    "Namespace": "default",
59    "Name": "volume id1",
60    "Topologies": [
61      {
62        "foo": "bar"
63      }
64    ],
65    "AccessMode": "multi-node-single-writer",
66    "AttachmentMode": "file-system",
67    "Schedulable": true,
68    "PluginID": "plugin-id1",
69    "Provider": "ebs",
70    "ControllerRequired": true,
71    "ControllersHealthy": 3,
72    "ControllersExpected": 3,
73    "NodesHealthy": 15,
74    "NodesExpected": 18,
75    "ResourceExhausted": 0,
76    "CreateIndex": 42,
77    "ModifyIndex": 64
78  }
79]
80```
81
82## Read Volume
83
84This endpoint reads information about a specific volume.
85
86| Method | Path                        | Produces           |
87| ------ | --------------------------- | ------------------ |
88| `GET`  | `/v1/volume/csi/:volume_id` | `application/json` |
89
90The table below shows this endpoint's support for
91[blocking queries](/api-docs#blocking-queries) and
92[required ACLs](/api-docs#acls).
93
94| Blocking Queries | ACL Required                |
95| ---------------- | --------------------------- |
96| `YES`            | `namespace:csi-read-volume` |
97
98### Parameters
99
100- `:volume_id` `(string: <required>)` - Specifies the ID of the
101  volume. This must be the full ID. This is specified as part of the
102  path.
103
104### Sample Request
105
106```shell-session
107$ curl \
108    https://localhost:4646/v1/volume/csi/volume-id1
109```
110
111### Sample Response
112
113```json
114{
115  "ID": "volume-id1",
116  "Name": "volume id1",
117  "Namespace": "default",
118  "ExternalID": "vol-abcdef",
119  "Topologies": [{ "foo": "bar" }],
120  "AccessMode": "multi-node-single-writer",
121  "AttachmentMode": "file-system",
122  "RequestedCapabilities": [
123    {
124      "AccessMode": "single-node-writer",
125      "AttachmentMode": "file-system"
126    },
127    {
128      "AccessMode": "single-node-writer",
129      "AttachmentMode": "block-device"
130    }
131  ],
132  "Allocations": [
133    {
134      "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
135      "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
136      "Name": "example.cache[0]",
137      "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
138      "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
139      "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",
140      "RescheduleTracker": {
141        "Events": [
142          {
143            "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
144            "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",
145            "RescheduleTime": 1517434161192946200,
146            "Delay": "5000000000"
147          }
148        ]
149      },
150      "JobID": "example",
151      "TaskGroup": "cache",
152      "DesiredStatus": "run",
153      "DesiredDescription": "",
154      "ClientStatus": "running",
155      "ClientDescription": "",
156      "TaskStates": {
157        "redis": {
158          "State": "running",
159          "FinishedAt": "0001-01-01T00:00:00Z",
160          "LastRestart": "0001-01-01T00:00:00Z",
161          "Restarts": 0,
162          "StartedAt": "2017-07-25T23:36:26.106431265Z",
163          "Failed": false,
164          "Events": [
165            {
166              "Type": "Received",
167              "Time": 1495747371795703800,
168              "FailsTask": false,
169              "RestartReason": "",
170              "SetupError": "",
171              "DriverError": "",
172              "ExitCode": 0,
173              "Signal": 0,
174              "Message": "",
175              "KillTimeout": 0,
176              "KillError": "",
177              "KillReason": "",
178              "StartDelay": 0,
179              "DownloadError": "",
180              "ValidationError": "",
181              "DiskLimit": 0,
182              "FailedSibling": "",
183              "VaultError": "",
184              "TaskSignalReason": "",
185              "TaskSignal": "",
186              "DriverMessage": ""
187            },
188            {
189              "Type": "Driver",
190              "Time": 1495747371798867200,
191              "FailsTask": false,
192              "RestartReason": "",
193              "SetupError": "",
194              "DriverError": "",
195              "ExitCode": 0,
196              "Signal": 0,
197              "Message": "",
198              "KillTimeout": 0,
199              "KillError": "",
200              "KillReason": "",
201              "StartDelay": 0,
202              "DownloadError": "",
203              "ValidationError": "",
204              "DiskLimit": 0,
205              "FailedSibling": "",
206              "VaultError": "",
207              "TaskSignalReason": "",
208              "TaskSignal": "",
209              "DriverMessage": "Downloading image redis:3.2"
210            },
211            {
212              "Type": "Started",
213              "Time": 1495747379525667800,
214              "FailsTask": false,
215              "RestartReason": "",
216              "SetupError": "",
217              "DriverError": "",
218              "ExitCode": 0,
219              "Signal": 0,
220              "Message": "",
221              "KillTimeout": 0,
222              "KillError": "",
223              "KillReason": "",
224              "StartDelay": 0,
225              "DownloadError": "",
226              "ValidationError": "",
227              "DiskLimit": 0,
228              "FailedSibling": "",
229              "VaultError": "",
230              "TaskSignalReason": "",
231              "TaskSignal": "",
232              "DriverMessage": ""
233            }
234          ]
235        }
236      },
237      "CreateIndex": 54,
238      "ModifyIndex": 57,
239      "CreateTime": 1495747371794276400,
240      "ModifyTime": 1495747371794276400
241    }
242  ],
243  "ReadAllocs": {
244    "a8198d79-cfdb-6593-a999-1e9adabcba2e": null
245  },
246  "WriteAllocs": {},
247  "Schedulable": true,
248  "PluginID": "plugin-id1",
249  "Provider": "ebs",
250  "Version": "1.0.1",
251  "ControllerRequired": true,
252  "ControllersHealthy": 3,
253  "ControllersExpected": 3,
254  "NodesHealthy": 15,
255  "NodesExpected": 18,
256  "ResourceExhausted": 0,
257  "CreateIndex": 42,
258  "ModifyIndex": 64
259}
260```
261
262## Register Volume
263
264This endpoint registers an external volume with Nomad. The volume must exist
265in the external storage provider (see [Create Volume] below). It is an error
266to register an already registered volume.
267
268| Method | Path                        | Produces           |
269| ------ | --------------------------- | ------------------ |
270| `PUT`  | `/v1/volume/csi/:volume_id` | `application/json` |
271
272The table below shows this endpoint's support for
273[blocking queries](/api-docs#blocking-queries) and
274[required ACLs](/api-docs#acls).
275
276| Blocking Queries | ACL Required                 |
277| ---------------- | ---------------------------- |
278| `NO`             | `namespace:csi-write-volume` |
279
280### Parameters
281
282- `:volume_id` `(string: <required>)` - Specifies the ID of the
283  volume. This must be the full ID. This is specified as part of the
284  path.
285
286### Sample Payload
287
288The payload must include a JSON document that describes the volume's
289parameters.
290
291```json
292{
293  "Volumes": [
294    {
295      "ExternalID": "vol-abcdef",
296      "ID": "volume-id1",
297      "Name": "volume one",
298      "Namespace": "default",
299      "PluginID": "plugin-id1",
300      "RequestedCapabilities": [
301        {
302          "AccessMode": "single-node-writer",
303          "AttachmentMode": "file-system"
304        },
305        {
306          "AccessMode": "single-node-writer",
307          "AttachmentMode": "block-device"
308        }
309      ],
310      "Secrets": {
311        "password": "xyzzy"
312      },
313      "Topologies": [{ "foo": "bar" }]
314    }
315  ]
316}
317```
318
319### Sample Request
320
321```shell-session
322$ curl \
323    --request PUT \
324    --data @payload.json \
325    https://localhost:4646/v1/volume/csi/volume-id1
326```
327
328## Create Volume
329
330This endpoint creates a volume in an external storage provider and registers
331it with Nomad. It is an error to create an already-registered volume. Only CSI
332plugins that implement the [Controller][csi_plugins_internals] interface with
333the `CREATE_DELETE_VOLUME` capability support this endpoint.
334
335| Method | Path                               | Produces           |
336| ------ | ---------------------------------- | ------------------ |
337| `PUT`  | `/v1/volume/csi/:volume_id/create` | `application/json` |
338
339The table below shows this endpoint's support for
340[blocking queries](/api-docs#blocking-queries) and
341[required ACLs](/api-docs#acls).
342
343| Blocking Queries | ACL Required                 |
344| ---------------- | ---------------------------- |
345| `NO`             | `namespace:csi-write-volume` |
346
347### Parameters
348
349- `:volume_id` `(string: <required>)` - Specifies the ID of the
350  volume. This must be the full ID. This is specified as part of the
351  path.
352
353### Sample Payload
354
355The payload must include a JSON document that describes the volume's
356parameters.
357
358```json
359{
360  "Volumes": [
361    {
362      "ID": "volume-id1",
363      "Name": "volume one",
364      "Namespace": "default",
365      "PluginID": "plugin-id1",
366      "MountOptions": {
367        "FsType": "ext4",
368        "MountFlags": ["ro", "noatime"],
369      },
370      "RequestedCapacityMin": 10737418240,
371      "RequestedCapacityMax": 21474836480,
372      "RequestedCapabilities": [
373        {
374          "AccessMode": "single-node-writer",
375          "AttachmentMode": "file-system"
376        },
377        {
378          "AccessMode": "single-node-writer",
379          "AttachmentMode": "block-device"
380        }
381      ],
382      "Secrets": {
383        "password": "xyzzy"
384      },
385      "SnapshotID": "snap-12345",
386      "Topologies": [{ "foo": "bar" }]
387    }
388  ]
389}
390```
391
392### Sample Request
393
394```shell-session
395$ curl \
396    --request PUT \
397    --data @payload.json \
398    https://localhost:4646/v1/volume/csi/volume-id1
399```
400
401
402## Deregister Volume
403
404This endpoint deregisters an external volume with Nomad. It is an error to
405deregister a volume that is in use.
406
407| Method   | Path                        | Produces           |
408| -------- | --------------------------- | ------------------ |
409| `DELETE` | `/v1/volume/csi/:volume_id` | `application/json` |
410
411The table below shows this endpoint's support for
412[blocking queries](/api-docs#blocking-queries) and
413[required ACLs](/api-docs#acls).
414
415| Blocking Queries | ACL Required                 |
416| ---------------- | ---------------------------- |
417| `NO`             | `namespace:csi-write-volume` |
418
419### Parameters
420
421- `:volume_id` `(string: <required>)` - Specifies the ID of the
422  volume. This must be the full ID. This is specified as part of the
423  path.
424
425- `force` `(bool: false)` - Force deregistration of the volume and immediately
426  drop claims for terminal allocations. Returns an error if the volume has
427  running allocations. This does not detach the volume from client nodes.
428  This is specified as a query string parameter.
429
430### Sample Request
431
432```shell-session
433$ curl \
434    --request DELETE \
435    https://localhost:4646/v1/volume/csi/volume-id1?force=false
436```
437
438## Delete Volume
439
440This endpoint deletes an external volume from the storage provider, and
441deregisters it from Nomad. It is an error to delete a volume that is in
442use. Only CSI plugins that implement the [Controller][csi_plugins_internals]
443interface with the `CREATE_DELETE_VOLUME` capability support this endpoint.
444
445| Method   | Path                               | Produces           |
446| -------- | ---------------------------------- | ------------------ |
447| `DELETE` | `/v1/volume/csi/:volume_id/delete` | `application/json` |
448
449The table below shows this endpoint's support for
450[blocking queries](/api-docs#blocking-queries) and
451[required ACLs](/api-docs#acls).
452
453| Blocking Queries | ACL Required                 |
454| ---------------- | ---------------------------- |
455| `NO`             | `namespace:csi-write-volume` |
456
457### Parameters
458
459- `:volume_id` `(string: <required>)` - Specifies the ID of the
460  volume. This must be the full ID. This is specified as part of the
461  path.
462
463
464### Sample Request
465
466```shell-session
467$ curl \
468    --request DELETE \
469    https://localhost:4646/v1/volume/csi/volume-id1/delete
470```
471
472
473## Detach Volume
474
475This endpoint detaches an external volume from a Nomad client node. It is an
476error to detach a volume that is in use.
477
478| Method   | Path                               | Produces           |
479| -------- | ---------------------------------- | ------------------ |
480| `DELETE` | `/v1/volume/csi/:volume_id/detach` | `application/json` |
481
482The table below shows this endpoint's support for
483[blocking queries](/api-docs#blocking-queries) and
484[required ACLs](/api-docs#acls).
485
486| Blocking Queries | ACL Required                 |
487| ---------------- | ---------------------------- |
488| `NO`             | `namespace:csi-write-volume` |
489
490### Parameters
491
492- `:volume_id` `(string: <required>)` - Specifies the ID of the
493  volume. This must be the full ID. This is specified as part of the
494  path.
495
496- `node` `(string: <required>)` - The node to detach the volume from.
497  This is specified as a query string parameter.
498
499### Sample Request
500
501```shell-session
502$ curl \
503    --request DELETE \
504    https://localhost:4646/v1/volume/csi/volume-id/detach?node=00000000-0000-0000-0000-000000000000
505```
506
507## List External Volumes
508
509This endpoint lists storage volumes that are known to the external storage
510provider but may not be registered with Nomad.  Only CSI plugins that
511implement the [Controller][csi_plugins_internals] interface with the
512`LIST_VOLUMES` capability support this endpoint.
513
514| Method | Path                   | Produces           |
515|--------|------------------------|--------------------|
516| `GET`  | `/v1/volumes/external` | `application/json` |
517
518The table below shows this endpoint's support for
519[blocking queries](/api-docs#blocking-queries) and
520[required ACLs](/api-docs#acls).
521
522| Blocking Queries | ACL Required                 |
523| ---------------- | ---------------------------- |
524| `YES`             | `namespace:csi-write-volume` |
525
526### Parameters
527
528- `plugin_id` `(string: "")` - Specifies a string to filter volumes
529  based on a plugin ID prefix. Because the value is decoded to bytes,
530  the prefix must have an even number of hexadecimal characters
531  (0-9a-f). This is specified as a query string parameter.
532
533- `next_token` `(string: "")` - This endpoint supports paging. The
534  `next_token` parameter accepts a string returned in a previous response's
535  `NextToken` field to request the next page of results.
536
537- `per_page` `(int: <required>)` - Specifies a maximum number of snapshots to
538  return for this request. The response will include a `NextToken` field that
539  can be passed to the next request to fetch additional pages.
540
541### Sample Request
542
543```shell-session
544$ curl \
545    https://localhost:4646/v1/volumes/external?&plugin_id=plugin-id1&per_page=2
546```
547
548### Sample Response
549
550```json
551{
552  "NextToken": "eyJ2IjoiMiIsImMiOiJLZ",
553  "Volumes": [
554    {
555      "ExternalID": "vol-37ac485e",
556      "CapacityBytes": 1000000,
557      "SnapshotID": "snap-12345",
558      "PublishedExternalNodeIDs": ["i-12345", "i-abcde"],
559      "IsAbnormal": false,
560      "Status": ""
561    },
562    {
563      "ExternalID": "vol-10ac4879",
564      "CapacityBytes": 1000000,
565      "SnapshotID": "snap-abcdef",
566      "PublishedExternalNodeIDs": ["i-12345", "i-abcde"],
567      "IsAbnormal": true,
568      "Status": "example error message from provider"
569    }
570  ]
571}
572```
573
574## Create Snapshot
575
576This endpoint creates a snapshot of a volume on the external storage
577provider. Only CSI plugins that implement the
578[Controller][csi_plugins_internals] interface with the
579`CREATE_DELETE_SNAPSHOT` capability support this endpoint.
580
581| Method   | Path                              | Produces           |
582| -------- | --------------------------------- | ------------------ |
583| `PUT`    | `/v1/volumes/snapshot/:volume_id` | `application/json` |
584
585The table below shows this endpoint's support for
586[blocking queries](/api-docs#blocking-queries) and
587[required ACLs](/api-docs#acls).
588
589| Blocking Queries | ACL Required                 |
590| ---------------- | ---------------------------- |
591| `NO`             | `namespace:csi-write-volume` |
592
593
594### Sample Payload
595
596The payload must include a JSON document that describes the snapshot's
597parameters.
598
599```json
600{
601  "Snapshots": [
602    {
603      "SourceVolumeID": "volume-id1",
604      "PluginID": "plugin-id1",
605      "Name": "mysnap",
606      "Secrets": {
607        "password": "xyzzy"
608      },
609      "Parameters": {
610        "example": "infrequent_access"
611      }
612    }
613  ]
614}
615```
616### Parameters
617
618- `:volume_id` `(string: <required>)` - Specifies the ID of the volume to
619  snapshot. This must be the full ID. This is specified as part of the path.
620
621### Sample Request
622
623```shell-session
624$ curl \
625    --request PUT \
626    --data @payload.json \
627    https://localhost:4646/v1/volume/csi/volume-id1/snapshot
628```
629
630### Sample Response
631
632```json
633{
634  "Snapshots": [
635    {
636      "ID": "snap-031f5f7e3406d594a",
637      "SizeBytes": 10737418240,
638      "CreateTime": 1617909982,
639      "IsReady": false,
640      "SourceVolumeID": "volume-id1"
641    }
642  ]
643}
644```
645
646## Delete Snapshot
647
648This endpoint deletes a volume snapshot from the external storage
649provider. Only CSI plugins that implement the
650[Controller][csi_plugins_internals] interface with the
651`CREATE_DELETE_SNAPSHOT` capability support this endpoint.
652
653| Method   | Path                   | Produces           |
654| -------- | ---------------------- | ------------------ |
655| `DELETE` | `/v1/volumes/snapshot` | `application/json` |
656
657The table below shows this endpoint's support for
658[blocking queries](/api-docs#blocking-queries) and
659[required ACLs](/api-docs#acls).
660
661| Blocking Queries | ACL Required                 |
662| ---------------- | ---------------------------- |
663| `NO`             | `namespace:csi-write-volume` |
664
665### Parameters
666
667- `plugin_id` `(string: <required>)` - Specifies the prefix of a CSI plugin ID
668  to perform the delete. Because the value is decoded to bytes, the prefix
669  must have an even number of hexadecimal characters (0-9a-f). This is
670  specified as a query string parameter.
671
672- `snapshot_id` `(string: <required>)` - Specifies the snapshot ID to
673  delete. This is specified as a query parameter.
674
675### Sample Request
676
677```shell-session
678$ curl \
679    --request DELETE \
680    https://localhost:4646/v1/volumes/snapshot
681```
682
683## List Snapshots
684
685This endpoint lists volume snapshots on the external storage provider. Only
686CSI plugins that implement the [Controller][csi_plugins_internals] interface
687with the `LIST_SNAPSHOTS` capability support this endpoint.
688
689
690| Method | Path                   | Produces           |
691| ------ | ---------------------- | ------------------ |
692| `GET`  | `/v1/volumes/snapshot` | `application/json` |
693
694The table below shows this endpoint's support for
695[blocking queries](/api-docs#blocking-queries) and
696[required ACLs](/api-docs#acls).
697
698| Blocking Queries | ACL Required                |
699| ---------------- | --------------------------- |
700| `YES`            | `namespace:csi-list-volume` |
701
702### Parameters
703
704- `plugin_id` `(string: <required>)` - Specifies the prefix of a CSI plugin ID
705  to perform the list. Because the value is decoded to bytes, the prefix must
706  have an even number of hexadecimal characters (0-9a-f). This is specified as
707  a query string parameter.
708
709- `next_token` `(string: "")` - This endpoint supports paging. The
710  `next_token` parameter accepts a string returned in a previous response's
711  `NextToken` field to request the next page of results.
712
713- `per_page` `(int: <required>)` - Specifies a maximum number of snapshots to
714  return for this request. The response will include a `NextToken` field that
715  can be passed to the next request to fetch additional pages.
716
717
718### Sample Request
719
720```shell-session
721$ curl \
722    https://localhost:4646/v1/volumes/snapshot?&plugin_id=plugin-id1&per_page=2
723```
724
725### Sample Response
726
727```json
728{
729  "NextToken": "eyJ2IjoiMiIsImMiOiJLZ",
730  "Snapshots": [
731    {
732      "CreateTime": 1227088980,
733      "ExternalSourceVolumeID": "vol-37ac485e",
734      "ID": "snap-9df717f4",
735      "IsReady": true,
736      "Parameters": null,
737      "PluginID": "aws-ebs0",
738      "SizeBytes": 2147483648
739    },
740    {
741      "CreateTime": 1227091232,
742      "ExternalSourceVolumeID": "vol-10ac4879",
743      "ID": "snap-5cf81835",
744      "IsReady": true,
745      "Parameters": null,
746      "PluginID": "aws-ebs0",
747      "SizeBytes": 11811160064
748    }
749  ]
750}
751```
752
753[csi]: https://github.com/container-storage-interface/spec
754[csi_plugin]: /docs/job-specification/csi_plugin
755[csi_plugins_internals]: /docs/internals/plugins/csi#csi-plugins
756[Create Volume]: #create-volume
757