From 98e9d0c95e4a60579e23359294310786c2cb1621 Mon Sep 17 00:00:00 2001 From: Thy Ton Date: Wed, 27 Sep 2023 22:35:22 -0700 Subject: [PATCH] add API docs for plugin runtimes (#23223) Co-authored-by: Tom Proctor Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> --- .../api-docs/system/plugins-catalog.mdx | 45 ++++- .../system/plugins-runtimes-catalog.mdx | 183 ++++++++++++++++++ website/data/api-docs-nav-data.json | 4 + 3 files changed, 225 insertions(+), 7 deletions(-) create mode 100644 website/content/api-docs/system/plugins-runtimes-catalog.mdx diff --git a/website/content/api-docs/system/plugins-catalog.mdx b/website/content/api-docs/system/plugins-catalog.mdx index 10e6c1ecf139..c2f912c920a8 100644 --- a/website/content/api-docs/system/plugins-catalog.mdx +++ b/website/content/api-docs/system/plugins-catalog.mdx @@ -69,13 +69,23 @@ $ curl \ "version": "v1.12.0+builtin.vault" }, ... + { + "builtin": false, + "name": "example-plugin", + "type": "secret", + "oci_image": "example-secret-plugin-oci-image", + "runtime": "example-runtime", + "version": "v1.0.0" + }, + ... ], "secret": [ "ad", "aws", "azure", "gcp", - "transit" + "transit", + "example-plugin", ] } } @@ -137,14 +147,23 @@ supplied name. - `type` `(string: )` – Specifies the type of this plugin. May be "auth", "database", or "secret". -- `version` `(string: "")` - Specifies the semantic version of this plugin. +- `oci_image` `(string: "")` - Specifies OCI image to run. If specified, setting `command`, + `args`, and `env` will update the container's entrypoint, args, and environment + variables (append-only) respectively. + +- `runtime` `(string: "")` - Specifies Vault plugin runtime to use if `oci_image` is specified. + See [/sys/plugins/runtimes/catalog](/vault/api-docs/system/plugins-runtimes-catalog) for additional information. + +- `version` `(string: "")` - Specifies the semantic version of the plugin. Used as the tag + when specifying `oci_image`, but with any leading 'v' trimmed. - `sha256` `(string: )` – This is the SHA256 sum of the plugin's - binary. Before a plugin is run it's SHA will be checked against this value, if - they do not match the plugin can not be run. + binary or the OCI image. Before a plugin is run, its SHA will be checked against this value. + If they do not match the plugin can not be run. -- `command` `(string: )` – Specifies the command used to execute the - plugin. This is relative to the plugin directory. e.g. `"myplugin"`. +- `command` `(string: )` - Specifies the command used to execute the + plugin. This is relative to the plugin directory. e.g. `"myplugin"`, or if `oci_image` + is also specified, it is relative to the image's working directory. - `args` `(array: [])` – Specifies the arguments used to execute the plugin. If the arguments are provided here, the `command` parameter should only contain @@ -163,6 +182,16 @@ supplied name. } ``` +### Sample payload using OCI image + +```json +{ + "sha256": "d150b9a0fbfddef9709d8ff92e5e6053ccd246b78632fc03b8548457026961a9", + "oci_image": "example-secret-plugin-oci-image", + "runtime": "example-runtime" +} +``` + ### Sample request ```shell-session @@ -211,7 +240,9 @@ $ curl \ "data": { "args": [], "builtin": false, - "command": "/tmp/vault-plugins/mysql-database-plugin", + "runtime": "example-runtime", + "oci_image": "example-secret-plugin-oci-image", + "command": "/example-secret-plugin", "name": "example-plugin", "sha256": "0TC5oPv93vlwnY/5Ll5gU8zSRreGMvwDuFSEVwJpYek=", "version": "v1.0.0" diff --git a/website/content/api-docs/system/plugins-runtimes-catalog.mdx b/website/content/api-docs/system/plugins-runtimes-catalog.mdx new file mode 100644 index 000000000000..a056942abc33 --- /dev/null +++ b/website/content/api-docs/system/plugins-runtimes-catalog.mdx @@ -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: )` – 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: )` – Specifies the plugin runtime type. Currently + only accepts "container". + +- `name` `(string: )` – 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: )` – Specifies OCI-compliant container runtime to use. + Default is "runsc", gVisor's OCI runtime. + +- `cgroup_parent` `(string: )` – 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: )` – Specifies cpu limit to set per container in billionths of a CPU. + Defaults to no limit. + +- `memory_bytes` `(int: )` – 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: )` – Specifies the type of this plugin runtime. Currently + only accepts "container". + +- `name` `(string: )` – 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: )` – Specifies the type of this plugin runtime. Currently + only accepts "container". + +- `name` `(string: )` – 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 +``` diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index cedccaed7761..930c43d6b00a 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -605,6 +605,10 @@ "title": "/sys/plugins/catalog", "path": "system/plugins-catalog" }, + { + "title": "/sys/plugins/runtimes/catalog", + "path": "system/plugins-runtimes-catalog" + }, { "title": "/sys/policy", "path": "system/policy"