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>

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: <required>)` – 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: <required>)` – 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
+  binary or the OCI image. Before a plugin is run, its SHA will be checked against this value.
-  they do not match the plugin can not be run.
+  If they do not match the plugin can not be run.
 
-- `command` `(string: <required>)` – Specifies the command used to execute the
+- `command` `(string: <required>)` - Specifies the command used to execute the
-  plugin. This is relative to the plugin directory. e.g. `"myplugin"`.
+  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"

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: <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
+```

website/data/api-docs-nav-data.json

@@ -605,6 +605,10 @@
         "title": "<code>/sys/plugins/catalog</code>",
         "path": "system/plugins-catalog"
       },
+      {
+        "title": "<code>/sys/plugins/runtimes/catalog</code>",
+        "path": "system/plugins-runtimes-catalog"
+      },
       {
         "title": "<code>/sys/policy</code>",
         "path": "system/policy"