diff --git a/website/data/api-navigation.js b/website/data/api-navigation.js index 3d9433957..be144e6cc 100644 --- a/website/data/api-navigation.js +++ b/website/data/api-navigation.js @@ -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' ] diff --git a/website/pages/api-docs/plugins.mdx b/website/pages/api-docs/plugins.mdx new file mode 100644 index 000000000..67fe25dae --- /dev/null +++ b/website/pages/api-docs/plugins.mdx @@ -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 + } + } + } + } +] +``` diff --git a/website/pages/api-docs/volumes.mdx b/website/pages/api-docs/volumes.mdx new file mode 100644 index 000000000..cf835175f --- /dev/null +++ b/website/pages/api-docs/volumes.mdx @@ -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: )`- 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: )`- 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: )`- 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 +```