mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-10-29 17:52:32 +00:00
backport of commit 98e9d0c95e (#23368)
Co-authored-by: Thy Ton <maithytonn@gmail.com>
This commit is contained in:
hc-github-team-secure-vault-core
committed by
GitHub
GitHub
parent
74bc20b52f
commit
e42b1b70e5
@@ -71,13 +71,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",
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -143,14 +153,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
|
||||
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: <required>)` – Specifies the command used to execute the
|
||||
plugin. This is relative to the plugin directory. e.g. `"myplugin"`.
|
||||
- `command` `(string: <required>)` - 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
|
||||
@@ -169,6 +188,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
|
||||
@@ -219,7 +248,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"
|
||||
|
||||
183
website/content/api-docs/system/plugins-runtimes-catalog.mdx
Normal file
183
website/content/api-docs/system/plugins-runtimes-catalog.mdx
Normal file
@@ -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
|
||||
```
|
||||
@@ -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"
|
||||
|
||||
Reference in New Issue
Block a user