mirror of
https://github.com/kemko/nomad.git
synced 2026-01-03 17:05:43 +03:00
CSI: HTTP API docs (#7435)
HTTP API documentation for the `/plugin` and `/volume` endpoints, to support CSI.
This commit is contained in:
Tim Gross
@@ -21,6 +21,7 @@ export default [
|
||||
'nodes',
|
||||
'metrics',
|
||||
'operator',
|
||||
'plugins',
|
||||
'quotas',
|
||||
'regions',
|
||||
'search',
|
||||
@@ -28,5 +29,6 @@ export default [
|
||||
'status',
|
||||
'system',
|
||||
'ui',
|
||||
'validate'
|
||||
'validate',
|
||||
'volumes'
|
||||
]
|
||||
|
||||
141
website/pages/api-docs/plugins.mdx
Normal file
141
website/pages/api-docs/plugins.mdx
Normal file
@@ -0,0 +1,141 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: Plugins - HTTP API
|
||||
sidebar_title: Plugins
|
||||
description: The `/plugin` endpoints are used to query for and interact with dynamic plugins.
|
||||
---
|
||||
|
||||
# Plugins HTTP API
|
||||
|
||||
The `/plugin` endpoints are used to query for and interact with
|
||||
dynamic plugins. Currently only Container Storage Interface (CSI)
|
||||
plugins are dynamic.
|
||||
|
||||
## List Plugins
|
||||
|
||||
This endpoint lists all dynamic plugins.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------- | ------------------ |
|
||||
| `GET` | `/v1/plugins` | `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-plugin` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `type` `(string: "")`- Specifies the type of plugin to
|
||||
query. Currently only supports `csi`. This is specified as a query
|
||||
string parameter. Returns an empty list if omitted.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell
|
||||
$ curl \
|
||||
https://localhost:4646/v1/plugins?type=csi
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"ID": "example",
|
||||
"Provider": "aws.ebs",
|
||||
"ControllerRequired": true,
|
||||
"ControllersHealthy": 2,
|
||||
"ControllersExpected": 3,
|
||||
"NodesHealthy": 14,
|
||||
"NodesExpected": 16,
|
||||
"CreateIndex": 52,
|
||||
"ModifyIndex": 93
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Read Plugin
|
||||
|
||||
Get details of a single plugin, including information about the
|
||||
plugin's job and client fingerprint data.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | --------------------------- | ------------------ |
|
||||
| `GET` | `/v1/plugin/csi/:plugin_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-plugin` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell
|
||||
$ curl \
|
||||
https://localhost:4646/v1/plugin/csi/example_plugin_id
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"ID": "example_plugin_id",
|
||||
"Topologies": [
|
||||
{"key": "val"},
|
||||
{"key": "val2"}
|
||||
],
|
||||
"Provider": "aws.ebs",
|
||||
"Version": "1.0.1",
|
||||
"ControllersRequired": true,
|
||||
"ControllersHealthy": 1,
|
||||
"Controllers": {
|
||||
"example_node_id": {
|
||||
"PluginID": "example_plugin_id",
|
||||
"Provider": "aws.ebs",
|
||||
"ProviderVersion": "1.0.1",
|
||||
"AllocID": "alloc-id",
|
||||
"Healthy": true,
|
||||
"HealthDescription": "healthy",
|
||||
"UpdateTime": "2020-01-31T00:00:00.000Z",
|
||||
"RequiresControllerPlugin": true,
|
||||
"RequiresTopologies": true,
|
||||
"ControllerInfo": {
|
||||
"SupportsReadOnlyAttach": true,
|
||||
"SupportsAttachDetach": true,
|
||||
"SupportsListVolumes": true,
|
||||
"SupportsListVolumesAttachedNodes": false
|
||||
}
|
||||
},
|
||||
"NodesHealthy": 1,
|
||||
"Nodes": {
|
||||
"example_node_id": {
|
||||
"PluginID": "example_plugin_id",
|
||||
"Provider": "aws.ebs",
|
||||
"ProviderVersion": "1.0.1",
|
||||
"AllocID": "alloc-id",
|
||||
"Healthy": true,
|
||||
"HealthDescription": "healthy",
|
||||
"UpdateTime": "2020-01-30T00:00:00.000Z",
|
||||
"RequiresControllerPlugin": true,
|
||||
"RequiresTopologies": true,
|
||||
"NodeInfo": {
|
||||
"ID": "example_node_id",
|
||||
"MaxVolumes": 51,
|
||||
"AccessibleTopology": {
|
||||
"key": "val2"
|
||||
},
|
||||
"RequiresNodeStageVolume": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
332
website/pages/api-docs/volumes.mdx
Normal file
332
website/pages/api-docs/volumes.mdx
Normal file
@@ -0,0 +1,332 @@
|
||||
---
|
||||
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
Block a user