github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/api-docs/plugins.mdx (about)

     1  ---
     2  layout: api
     3  page_title: Plugins - HTTP API
     4  description: The `/plugin` endpoints are used to query for and interact with dynamic plugins.
     5  ---
     6  
     7  # Plugins HTTP API
     8  
     9  The `/plugin` endpoints are used to query for and interact with
    10  dynamic plugins. Currently only Container Storage Interface (CSI)
    11  plugins are dynamic.
    12  
    13  ## List Plugins
    14  
    15  This endpoint lists all dynamic plugins.
    16  
    17  | Method | Path          | Produces           |
    18  | ------ | ------------- | ------------------ |
    19  | `GET`  | `/v1/plugins` | `application/json` |
    20  
    21  The table below shows this endpoint's support for
    22  [blocking queries](/api-docs#blocking-queries) and
    23  [required ACLs](/api-docs#acls).
    24  
    25  | Blocking Queries | ACL Required                |
    26  | ---------------- | --------------------------- |
    27  | `YES`            | `namespace:csi-list-plugin` |
    28  
    29  ### Parameters
    30  
    31  - `type` `(string: "")`- Specifies the type of plugin to
    32    query. Currently only supports `csi`. This is specified as a query
    33    string parameter. Returns an empty list if omitted.
    34  
    35  ### Sample Request
    36  
    37  ```shell-session
    38  $ curl \
    39      https://localhost:4646/v1/plugins?type=csi
    40  ```
    41  
    42  ### Sample Response
    43  
    44  ```json
    45  [
    46    {
    47      "ID": "example",
    48      "Provider": "aws.ebs",
    49      "ControllerRequired": true,
    50      "ControllersHealthy": 2,
    51      "ControllersExpected": 3,
    52      "NodesHealthy": 14,
    53      "NodesExpected": 16,
    54      "CreateIndex": 52,
    55      "ModifyIndex": 93
    56    }
    57  ]
    58  ```
    59  
    60  ## Read Plugin
    61  
    62  Get details of a single plugin, including information about the
    63  plugin's job and client fingerprint data.
    64  
    65  | Method | Path                        | Produces           |
    66  | ------ | --------------------------- | ------------------ |
    67  | `GET`  | `/v1/plugin/csi/:plugin_id` | `application/json` |
    68  
    69  The table below shows this endpoint's support for
    70  [blocking queries](/api-docs#blocking-queries) and
    71  [required ACLs](/api-docs#acls).
    72  
    73  | Blocking Queries | ACL Required                |
    74  | ---------------- | --------------------------- |
    75  | `YES`            | `namespace:csi-read-plugin` |
    76  
    77  ### Sample Request
    78  
    79  ```shell-session
    80  $ curl \
    81      https://localhost:4646/v1/plugin/csi/example_plugin_id
    82  ```
    83  
    84  ### Sample Response
    85  
    86  ```json
    87  [
    88    {
    89      "ID": "example_plugin_id",
    90      "Provider": "aws.ebs",
    91      "Version": "1.0.1",
    92      "ControllersRequired": true,
    93      "ControllersHealthy": 1,
    94      "Controllers": {
    95        "example_node_id": {
    96          "PluginID": "example_plugin_id",
    97          "Provider": "aws.ebs",
    98          "ProviderVersion": "1.0.1",
    99          "AllocID": "alloc-id",
   100          "Healthy": true,
   101          "HealthDescription": "healthy",
   102          "UpdateTime": "2020-01-31T00:00:00.000Z",
   103          "RequiresControllerPlugin": true,
   104          "RequiresTopologies": true,
   105          "ControllerInfo": {
   106            "SupportsReadOnlyAttach": true,
   107            "SupportsAttachDetach": true,
   108            "SupportsListVolumes": true,
   109            "SupportsListVolumesAttachedNodes": false
   110          }
   111        }
   112      },
   113      "NodesHealthy": 1,
   114      "Nodes": {
   115        "example_node_id": {
   116          "PluginID": "example_plugin_id",
   117          "Provider": "aws.ebs",
   118          "ProviderVersion": "1.0.1",
   119          "AllocID": "alloc-id",
   120          "Healthy": true,
   121          "HealthDescription": "healthy",
   122          "UpdateTime": "2020-01-30T00:00:00.000Z",
   123          "RequiresControllerPlugin": true,
   124          "RequiresTopologies": true,
   125          "NodeInfo": {
   126            "ID": "example_node_id",
   127            "MaxVolumes": 51,
   128            "AccessibleTopology": {
   129              "key": "val2"
   130            },
   131            "RequiresNodeStageVolume": true
   132          }
   133        }
   134      }
   135    }
   136  ]
   137  ```