luxolus
/
open-nomad
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-nomad/website/pages/api-docs/volumes.mdx

333 lines
9.0 KiB
Plaintext
Raw Blame History

---
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: <required>)`- 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: <required>)`- 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: <required>)`- 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
```
Reference in New Issue View Git Blame Copy Permalink