github.com/adityamillind98/nomad@v0.11.8/website/pages/api-docs/volumes.mdx (about) 1 --- 2 layout: api 3 page_title: Volumes - HTTP API 4 sidebar_title: Volumes 5 description: The `/volume` endpoints are used to query for and interact with volumes. 6 --- 7 8 # Volumes HTTP API 9 10 The `/volume` endpoints are used to query for and interact with volumes. 11 12 ## List Volumes 13 14 This endpoint lists all volumes. 15 16 | Method | Path | Produces | 17 | ------ | ------------- | ------------------ | 18 | `GET` | `/v1/volumes` | `application/json` | 19 20 The 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": "volume-id1", 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 84 This endpoint reads information about a specific volume. 85 86 | Method | Path | Produces | 87 | ------ | --------------------------- | ------------------ | 88 | `GET` | `/v1/volume/csi/:volume_id` | `application/json` | 89 90 The 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": "volume-id1", 119 "Topologies": [{ "foo": "bar" }], 120 "AccessMode": "multi-node-single-writer", 121 "AttachmentMode": "file-system", 122 "Allocations": [ 123 { 124 "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e", 125 "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 126 "Name": "example.cache[0]", 127 "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", 128 "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 129 "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b", 130 "RescheduleTracker": { 131 "Events": [ 132 { 133 "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 134 "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e", 135 "RescheduleTime": 1517434161192946200, 136 "Delay": "5000000000" 137 } 138 ] 139 }, 140 "JobID": "example", 141 "TaskGroup": "cache", 142 "DesiredStatus": "run", 143 "DesiredDescription": "", 144 "ClientStatus": "running", 145 "ClientDescription": "", 146 "TaskStates": { 147 "redis": { 148 "State": "running", 149 "FinishedAt": "0001-01-01T00:00:00Z", 150 "LastRestart": "0001-01-01T00:00:00Z", 151 "Restarts": 0, 152 "StartedAt": "2017-07-25T23:36:26.106431265Z", 153 "Failed": false, 154 "Events": [ 155 { 156 "Type": "Received", 157 "Time": 1495747371795703800, 158 "FailsTask": false, 159 "RestartReason": "", 160 "SetupError": "", 161 "DriverError": "", 162 "ExitCode": 0, 163 "Signal": 0, 164 "Message": "", 165 "KillTimeout": 0, 166 "KillError": "", 167 "KillReason": "", 168 "StartDelay": 0, 169 "DownloadError": "", 170 "ValidationError": "", 171 "DiskLimit": 0, 172 "FailedSibling": "", 173 "VaultError": "", 174 "TaskSignalReason": "", 175 "TaskSignal": "", 176 "DriverMessage": "" 177 }, 178 { 179 "Type": "Driver", 180 "Time": 1495747371798867200, 181 "FailsTask": false, 182 "RestartReason": "", 183 "SetupError": "", 184 "DriverError": "", 185 "ExitCode": 0, 186 "Signal": 0, 187 "Message": "", 188 "KillTimeout": 0, 189 "KillError": "", 190 "KillReason": "", 191 "StartDelay": 0, 192 "DownloadError": "", 193 "ValidationError": "", 194 "DiskLimit": 0, 195 "FailedSibling": "", 196 "VaultError": "", 197 "TaskSignalReason": "", 198 "TaskSignal": "", 199 "DriverMessage": "Downloading image redis:3.2" 200 }, 201 { 202 "Type": "Started", 203 "Time": 1495747379525667800, 204 "FailsTask": false, 205 "RestartReason": "", 206 "SetupError": "", 207 "DriverError": "", 208 "ExitCode": 0, 209 "Signal": 0, 210 "Message": "", 211 "KillTimeout": 0, 212 "KillError": "", 213 "KillReason": "", 214 "StartDelay": 0, 215 "DownloadError": "", 216 "ValidationError": "", 217 "DiskLimit": 0, 218 "FailedSibling": "", 219 "VaultError": "", 220 "TaskSignalReason": "", 221 "TaskSignal": "", 222 "DriverMessage": "" 223 } 224 ] 225 } 226 }, 227 "CreateIndex": 54, 228 "ModifyIndex": 57, 229 "CreateTime": 1495747371794276400, 230 "ModifyTime": 1495747371794276400 231 } 232 ], 233 "Schedulable": true, 234 "PluginID": "plugin-id1", 235 "Provider": "ebs", 236 "Version": "1.0.1", 237 "ControllerRequired": true, 238 "ControllersHealthy": 3, 239 "ControllersExpected": 3, 240 "NodesHealthy": 15, 241 "NodesExpected": 18, 242 "ResourceExhausted": 0, 243 "CreateIndex": 42, 244 "ModifyIndex": 64 245 } 246 ``` 247 248 ## Register Volume 249 250 This endpoint registers an external volume with Nomad. It is an error 251 to register an existing volume. 252 253 | Method | Path | Produces | 254 | ------ | --------------------------- | ------------------ | 255 | `PUT` | `/v1/volume/csi/:volume_id` | `application/json` | 256 257 The table below shows this endpoint's support for 258 [blocking queries](/api-docs#blocking-queries) and 259 [required ACLs](/api-docs#acls). 260 261 | Blocking Queries | ACL Required | 262 | ---------------- | ---------------------------- | 263 | `NO` | `namespace:csi-write-volume` | 264 265 ### Parameters 266 267 - `:volume_id` `(string: <required>)`- Specifies the ID of the 268 volume. This must be the full ID. This is specified as part of the 269 path. 270 271 ### Sample Payload 272 273 The payload must include a JSON document that described the volume's 274 parameters. 275 276 ```json 277 { 278 "ID": "volume-id1", 279 "Name": "volume id1", 280 "Namespace": "default", 281 "ExternalID": "volume-id1", 282 "Topologies": [{ "foo": "bar" }], 283 "AccessMode": "multi-node-single-writer", 284 "AttachmentMode": "file-system", 285 "PluginID": "plugin-id1" 286 } 287 ``` 288 289 ### Sample Request 290 291 ```shell-session 292 $ curl \ 293 --request PUT \ 294 --data @payload.json \ 295 https://localhost:4646/v1/volume/csi/volume-id1 296 ``` 297 298 ## Delete Volume 299 300 This endpoint deregisters an external volume with Nomad. It is an 301 error to deregister a volume that is in use. 302 303 | Method | Path | Produces | 304 | ------- | --------------------------- | ------------------ | 305 | `DELTE` | `/v1/volume/csi/:volume_id` | `application/json` | 306 307 The table below shows this endpoint's support for 308 [blocking queries](/api-docs#blocking-queries) and 309 [required ACLs](/api-docs#acls). 310 311 | Blocking Queries | ACL Required | 312 | ---------------- | ---------------------------- | 313 | `NO` | `namespace:csi-write-volume` | 314 315 ### Parameters 316 317 - `:volume_id` `(string: <required>)`- Specifies the ID of the 318 volume. This must be the full ID. This is specified as part of the 319 path. 320 321 ### Sample Request 322 323 ```shell-session 324 $ curl \ 325 --request DELETE \ 326 --data @payload.json \ 327 https://localhost:4646/v1/volume/csi/volume-id1 328 ```