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