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

376 lines
10 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-session
$ 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-session
$ 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
}
],
"ReadAllocs": {
"a8198d79-cfdb-6593-a999-1e9adabcba2e": null
},
"WriteAllocs": {},
"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 |
| ---------------- | ---------------------------- |
| `NO` | `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
{
"Volumes": [
{
"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-session
$ 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 |
| -------- | --------------------------- | ------------------ |
| `DELETE` | `/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 |
| ---------------- | ---------------------------- |
| `NO` | `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.
- `force` `(bool: false)`- Force deregistration of the volume and immediately
drop claims for terminal allocations. Returns an error if the volume has
running allocations. This does not detach the volume from client nodes.
This is specified as a query string parameter.
### Sample Request
```shell-session
$ curl \
--request DELETE \
--data @payload.json \
https://localhost:4646/v1/volume/csi/volume-id1?force=false
```
## Detach Volume
This endpoint detaches an external volume from a Nomad client node. It is an
error to detach a volume that is in use.
| Method | Path | Produces |
| -------- | ---------------------------------- | ------------------ |
| `DELETE` | `/v1/volume/csi/:volume_id/detach` | `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 |
| ---------------- | ---------------------------- |
| `NO` | `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.
- `node` `(string: <required>)`- The node to detach the volume from.
This is specified as a query string parameter.
### Sample Request
```shell-session
$ curl \
--request DELETE \
https://localhost:4646/v1/volume/csi/volume-id/detach?node=00000000-0000-0000-0000-000000000000
```
Reference in New Issue View Git Blame Copy Permalink