-
Notifications
You must be signed in to change notification settings - Fork 4.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
add API docs for plugin runtimes (#23223)
Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com> Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
- Loading branch information
3 people
committed
Sep 28, 2023
1 parent
a6ee197
commit 98e9d0c
Showing
3 changed files
with
225 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
183 changes: 183 additions & 0 deletions
183
website/content/api-docs/system/plugins-runtimes-catalog.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,183 @@ | ||
| --- | ||
| layout: api | ||
| page_title: /sys/plugins/runtimes/catalog - HTTP API | ||
| description: The `/sys/plugins/runtimes/catalog` endpoint is used to manage plugin runtimes. | ||
| --- | ||
|
|
||
| # `/sys/plugins/runtimes/catalog` | ||
|
|
||
| The `/sys/plugins/runtimes/catalog` manages plugin runtimes in your Vault catalog by reading, registering, | ||
| updating, and removing plugin runtime information. Plugin runtimes must be registered before use, and | ||
| once registered, backends can use the plugin runtime by referencing them when registering a plugin. | ||
|
|
||
| ## LIST plugin runtimes | ||
|
|
||
| The list endpoint returns a list of the plugin runtimes in the catalog. | ||
|
|
||
| - **`sudo` required** – This endpoint requires `sudo` capability in addition to | ||
| any path-specific capabilities. | ||
|
|
||
| | Method | Path | | ||
| | :----- | :--------------------- | | ||
| | `LIST` | `/sys/plugins/runtimes/catalog` | | ||
| | `GET` | `/sys/plugins/runtimes/catalog` | | ||
| | `LIST` | `/sys/plugins/runtimes/catalog?type=:type` | | ||
| | `GET` | `/sys/plugins/runtimes/catalog?type=:type` | | ||
|
|
||
| ### Parameters | ||
|
|
||
| - `type` `(string: <required>)` – Specifies the plugin runtime type to list. Currently | ||
| only accepts "container". | ||
|
|
||
| ### Sample request | ||
|
|
||
| ```shell-session | ||
| $ curl \ | ||
| --header "X-Vault-Token: ..." \ | ||
| --request LIST | ||
| http://127.0.0.1:8200/v1/sys/plugins/runtimes/catalog | ||
| ``` | ||
|
|
||
| ### Sample response | ||
|
|
||
| ```json | ||
| { | ||
| "data": { | ||
| "runtimes": [ | ||
| { | ||
| "name": "example-plugin-runtime", | ||
| "type": "container", | ||
| "oci_runtime": "example-oci-runtime", | ||
| "cgroup_parent": "/examplelimit/", | ||
| "cpu_nanos": 1000, | ||
| "memory_bytes": 10000000 | ||
| }, | ||
| ... | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Register plugin runtime | ||
|
|
||
| The registration endpoint registers a new plugin runtime, or updates an existing one with the | ||
| supplied type and name. | ||
|
|
||
| - **`sudo` required** – This endpoint requires `sudo` capability in addition to | ||
| any path-specific capabilities. | ||
|
|
||
| | Method | Path | | ||
| | :----- | :--------------------------------- | | ||
| | `POST` | `/sys/plugins/runtimes/catalog/:type/:name` | | ||
|
|
||
| ### Parameters | ||
|
|
||
| - `type` `(string: <required>)` – Specifies the plugin runtime type. Currently | ||
| only accepts "container". | ||
|
|
||
| - `name` `(string: <required>)` – Part of the request URL. Specifies the plugin runtime name. | ||
| Use the runtime name to look up plugin runtimes in the catalog. | ||
|
|
||
| - `oci_runtime` `(string: <optional>)` – Specifies OCI-compliant container runtime to use. | ||
| Default is "runsc", gVisor's OCI runtime. | ||
|
|
||
| - `cgroup_parent` `(string: <optional>)` – Specifies the parent cgroup to set for each container. | ||
| Use the cgroup to control the total resource usage for a group of plugins. | ||
|
|
||
| - `cpu_nanos` `(int: <optional>)` – Specifies cpu limit to set per container in billionths of a CPU. | ||
| Defaults to no limit. | ||
|
|
||
| - `memory_bytes` `(int: <optional>)` – Specifies memory limit to set per container in bytes. | ||
| Defaults to no limit. | ||
|
|
||
| ### Sample payload | ||
|
|
||
| ```json | ||
| { | ||
| "oci_runtime": "example-oci-runtime", | ||
| "cgroup_parent": "/examplelimit/", | ||
| "cpu_nanos": 1000, | ||
| "memory_bytes": 10000000 | ||
| } | ||
| ``` | ||
|
|
||
| ### Sample request | ||
|
|
||
| ```shell-session | ||
| $ curl \ | ||
| --header "X-Vault-Token: ..." \ | ||
| --request POST \ | ||
| --data @payload.json \ | ||
| http://127.0.0.1:8200/v1/sys/plugins/runtimes/catalog/container/example-plugin-runtime | ||
| ``` | ||
|
|
||
| ## Read plugin runtime | ||
|
|
||
| The read endpoint returns the configuration data for the plugin runtime with the given type and name. | ||
|
|
||
| - **`sudo` required** – This endpoint requires `sudo` capability in addition to | ||
| any path-specific capabilities. | ||
|
|
||
| | Method | Path | | ||
| | :----- | :-------------------------------------------------- | | ||
| | `GET` | `/sys/plugins/runtimes/catalog/:type/:name` | | ||
|
|
||
| ### Parameters | ||
|
|
||
| - `type` `(string: <required>)` – Specifies the type of this plugin runtime. Currently | ||
| only accepts "container". | ||
|
|
||
| - `name` `(string: <required>)` – Part of the request URL. Specifies the name of the plugin runtime to retrieve. | ||
|
|
||
|
|
||
| ### Sample request | ||
|
|
||
| ```shell-session | ||
| $ curl \ | ||
| --header "X-Vault-Token: ..." \ | ||
| --request GET \ | ||
| http://127.0.0.1:8200/v1/sys/plugins/runtimes/catalog/container/example-plugin-runtime | ||
| ``` | ||
|
|
||
| ### Sample response | ||
|
|
||
| ```json | ||
| { | ||
| "data": { | ||
| "name": "example-plugin-runtime", | ||
| "type": "container", | ||
| "oci_runtime": "example-oci-runtime", | ||
| "cgroup_parent": "/examplelimit/", | ||
| "cpu_nanos": 1000, | ||
| "memory_bytes": 10000000 | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Remove plugin runtime from catalog | ||
|
|
||
| The remove endpoint removes the plugin runtime with the given type and name. Note that | ||
| the request will fail if any registered plugin references the plugin runtime. | ||
|
|
||
| - **`sudo` required** – This endpoint requires `sudo` capability in addition to | ||
| any path-specific capabilities. | ||
|
|
||
| | Method | Path | | ||
| | :------- | :-------------------------------------------------- | | ||
| | `DELETE` | `/sys/plugins/runtimes/catalog/:type/:name` | | ||
|
|
||
| ### Parameters | ||
|
|
||
| - `type` `(string: <required>)` – Specifies the type of this plugin runtime. Currently | ||
| only accepts "container". | ||
|
|
||
| - `name` `(string: <required>)` – Part of the request URL. Specifies the name of the plugin runtime to delete. | ||
|
|
||
| ### Sample request | ||
|
|
||
| ```shell-session | ||
| $ curl \ | ||
| --header "X-Vault-Token: ..." \ | ||
| --request DELETE \ | ||
| http://127.0.0.1:8200/v1/sys/plugins/runtimes/catalog/container/example-plugin-runtime | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters