--- layout: api page_title: Volumes - HTTP API sidebar_title: Volumes description: The `/volume` endpoints are used to query for and interact with volumes. --- # 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](/api-docs#blocking-queries) and [required ACLs](/api-docs#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 ```shell $ curl \ https://localhost:4646/v1/volumes?type=csi&node_id=foo&plugin_id=plugin-id1 ``` ### Sample Response ```json [ { "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](/api-docs#blocking-queries) and [required ACLs](/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | -------------------- | | `YES` | `namespace:csi-read-volume` | ### Parameters - `:volume_id` `(string: )`- Specifies the ID of the volume. This must be the full ID. This is specified as part of the path. ### Sample Request ```shell $ curl \ https://localhost:4646/v1/volume/csi/volume-id1 ``` ### Sample Response ```json { "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](/api-docs#blocking-queries) and [required ACLs](/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | -------------------- | | `YES` | `namespace:csi-write-volume` | ### Parameters - `:volume_id` `(string: )`- 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. ```json { "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 ```shell $ 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](/api-docs#blocking-queries) and [required ACLs](/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | -------------------- | | `YES` | `namespace:csi-write-volume` | ### Parameters - `:volume_id` `(string: )`- Specifies the ID of the volume. This must be the full ID. This is specified as part of the path. ### Sample Request ```shell $ curl \ --request DELETE \ --data @payload.json \ https://localhost:4646/v1/volume/csi/volume-id1 ```