mirror of
https://github.com/kemko/nomad.git
synced 2026-01-07 02:45:42 +03:00
fbefdb98c3
The soundness guarantees of the CSI specification leave a little to be desired in our ability to provide a 100% reliable automated solution for managing volumes. This changeset provides a new command to bridge this gap by providing the operator the ability to intervene. The command doesn't take an allocation ID so that the operator doesn't have to keep track of alloc IDs that may have been GC'd. Handle this case in the unpublish RPC by sending the client RPC for all the terminal/nil allocs on the selected node.
368 lines
10 KiB
Plaintext
368 lines
10 KiB
Plaintext
---
|
|
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
|
|
}
|
|
],
|
|
"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
|
|
{
|
|
"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.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request DELETE \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/volume/csi/volume-id/detach
|
|
```
|