github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/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 "ReadAllocs": { 234 "a8198d79-cfdb-6593-a999-1e9adabcba2e": null 235 }, 236 "WriteAllocs": {}, 237 "Schedulable": true, 238 "PluginID": "plugin-id1", 239 "Provider": "ebs", 240 "Version": "1.0.1", 241 "ControllerRequired": true, 242 "ControllersHealthy": 3, 243 "ControllersExpected": 3, 244 "NodesHealthy": 15, 245 "NodesExpected": 18, 246 "ResourceExhausted": 0, 247 "CreateIndex": 42, 248 "ModifyIndex": 64 249 } 250 ``` 251 252 ## Register Volume 253 254 This endpoint registers an external volume with Nomad. It is an error 255 to register an existing volume. 256 257 | Method | Path | Produces | 258 | ------ | --------------------------- | ------------------ | 259 | `PUT` | `/v1/volume/csi/:volume_id` | `application/json` | 260 261 The table below shows this endpoint's support for 262 [blocking queries](/api-docs#blocking-queries) and 263 [required ACLs](/api-docs#acls). 264 265 | Blocking Queries | ACL Required | 266 | ---------------- | ---------------------------- | 267 | `NO` | `namespace:csi-write-volume` | 268 269 ### Parameters 270 271 - `:volume_id` `(string: <required>)`- Specifies the ID of the 272 volume. This must be the full ID. This is specified as part of the 273 path. 274 275 ### Sample Payload 276 277 The payload must include a JSON document that described the volume's 278 parameters. 279 280 ```json 281 { 282 "Volumes": [ 283 { 284 "ID": "volume-id1", 285 "Name": "volume id1", 286 "Namespace": "default", 287 "ExternalID": "volume-id1", 288 "Topologies": [{ "foo": "bar" }], 289 "AccessMode": "multi-node-single-writer", 290 "AttachmentMode": "file-system", 291 "PluginID": "plugin-id1" 292 } 293 ] 294 } 295 ``` 296 297 ### Sample Request 298 299 ```shell-session 300 $ curl \ 301 --request PUT \ 302 --data @payload.json \ 303 https://localhost:4646/v1/volume/csi/volume-id1 304 ``` 305 306 ## Delete Volume 307 308 This endpoint deregisters an external volume with Nomad. It is an error to 309 deregister a volume that is in use. 310 311 | Method | Path | Produces | 312 | -------- | --------------------------- | ------------------ | 313 | `DELETE` | `/v1/volume/csi/:volume_id` | `application/json` | 314 315 The table below shows this endpoint's support for 316 [blocking queries](/api-docs#blocking-queries) and 317 [required ACLs](/api-docs#acls). 318 319 | Blocking Queries | ACL Required | 320 | ---------------- | ---------------------------- | 321 | `NO` | `namespace:csi-write-volume` | 322 323 ### Parameters 324 325 - `:volume_id` `(string: <required>)`- Specifies the ID of the 326 volume. This must be the full ID. This is specified as part of the 327 path. 328 329 - `force` `(bool: false)`- Force deregistration of the volume and immediately 330 drop claims for terminal allocations. Returns an error if the volume has 331 running allocations. This does not detach the volume from client nodes. 332 This is specified as a query string parameter. 333 334 ### Sample Request 335 336 ```shell-session 337 $ curl \ 338 --request DELETE \ 339 --data @payload.json \ 340 https://localhost:4646/v1/volume/csi/volume-id1?force=false 341 ``` 342 343 ## Detach Volume 344 345 This endpoint detaches an external volume from a Nomad client node. It is an 346 error to detach a volume that is in use. 347 348 | Method | Path | Produces | 349 | -------- | ---------------------------------- | ------------------ | 350 | `DELETE` | `/v1/volume/csi/:volume_id/detach` | `application/json` | 351 352 The table below shows this endpoint's support for 353 [blocking queries](/api-docs#blocking-queries) and 354 [required ACLs](/api-docs#acls). 355 356 | Blocking Queries | ACL Required | 357 | ---------------- | ---------------------------- | 358 | `NO` | `namespace:csi-write-volume` | 359 360 ### Parameters 361 362 - `:volume_id` `(string: <required>)`- Specifies the ID of the 363 volume. This must be the full ID. This is specified as part of the 364 path. 365 366 - `node` `(string: <required>)`- The node to detach the volume from. 367 This is specified as a query string parameter. 368 369 ### Sample Request 370 371 ```shell-session 372 $ curl \ 373 --request DELETE \ 374 https://localhost:4646/v1/volume/csi/volume-id/detach?node=00000000-0000-0000-0000-000000000000 375 ```