mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-24 16:11:08 +02:00
299 lines
8.3 KiB
Plaintext
299 lines
8.3 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: /sys/plugins/catalog - HTTP API
|
||
description: The `/sys/plugins/catalog` endpoint is used to manage plugins.
|
||
---
|
||
|
||
# `/sys/plugins/catalog`
|
||
|
||
The `/sys/plugins/catalog` endpoint is used to read, register, update, and
|
||
remove plugins in Vault's catalog. Plugins must be registered before use, and
|
||
once registered backends can use the plugin by querying the catalog.
|
||
|
||
## LIST plugins
|
||
|
||
This endpoint lists the plugins in the catalog by type.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------------- |
|
||
| `GET` | `/sys/plugins/catalog` |
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/sys/plugins/catalog
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"auth": [
|
||
"aws",
|
||
"azure",
|
||
"custom-auth-plugin",
|
||
"gcp",
|
||
"ldap"
|
||
],
|
||
"database": [
|
||
"cassandra-database-plugin",
|
||
"mssql-database-plugin",
|
||
"mysql-database-plugin",
|
||
"postgresql-database-plugin"
|
||
],
|
||
"detailed": [
|
||
{
|
||
"builtin": true,
|
||
"deprecation_status": "supported",
|
||
"name": "aws",
|
||
"type": "auth",
|
||
"version": "v1.12.0+builtin.vault"
|
||
},
|
||
...
|
||
{
|
||
"builtin": true,
|
||
"deprecation_status": "supported",
|
||
"name": "cassandra-database-plugin",
|
||
"type": "database",
|
||
"version": "v1.12.0+builtin.vault"
|
||
},
|
||
...
|
||
{
|
||
"builtin": true,
|
||
"deprecation_status": "supported",
|
||
"name": "aws",
|
||
"type": "secret",
|
||
"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",
|
||
"example-plugin",
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## LIST plugins
|
||
|
||
This endpoint lists the plugins in the catalog by type.
|
||
|
||
| Method | Path |
|
||
| :----- | :------------------------------ |
|
||
| `LIST` | `/sys/plugins/catalog/auth` |
|
||
| `LIST` | `/sys/plugins/catalog/database` |
|
||
| `LIST` | `/sys/plugins/catalog/secret` |
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST
|
||
http://127.0.0.1:8200/v1/sys/plugins/catalog/auth
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keys": [
|
||
"aws",
|
||
"azure",
|
||
"custom-auth-plugin",
|
||
"gcp",
|
||
"ldap"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Register plugin
|
||
|
||
This endpoint registers a new plugin, or updates an existing one with the
|
||
supplied name.
|
||
|
||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||
any path-specific capabilities.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------------------------- |
|
||
| `POST` | `/sys/plugins/catalog/:type/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name for this plugin. The name
|
||
is what is used to look up plugins in the catalog. This is part of the request
|
||
URL. Enterprise plugin names must match the name listed on the
|
||
[HashiCorp releases page](https://releases.hashicorp.com/)
|
||
|
||
- `type` `(string: <required>)` – Specifies the type of this plugin. May be
|
||
"auth", "database", or "secret".
|
||
|
||
- `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>)` – The SHA256 sum of a Community plugin
|
||
binary or the OCI image. Before a plugin is run, its SHA will be checked against this value.
|
||
If the actual SHA of the plugin binary and the SHA provided in `sha256` do not match, Vault will not run the plugin. The `sha256` parameter is only required for Community plugins. Enterprise plugins do not require SHA confirmation.
|
||
|
||
- `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.
|
||
The `command` parameter is only required for Community plugins as
|
||
the run command is known for Enterprise plugins.
|
||
|
||
- `args` `(array: [])` – Specifies the arguments used to execute the plugin. If
|
||
the arguments are provided here, the `command` parameter should only contain
|
||
the named program. e.g. `"--my_flag=1"`.
|
||
|
||
- `env` `(array: [])` – Specifies the environment variables used during the
|
||
execution of the plugin. Each entry is of the form "key=value". e.g
|
||
`"FOO=BAR"`.
|
||
|
||
### Sample payload
|
||
|
||
#### Community plugins
|
||
|
||
```json
|
||
{
|
||
"sha256": "d130b9a0fbfddef9709d8ff92e5e6053ccd246b78632fc03b8548457026961e9",
|
||
"command": "mysql-database-plugin",
|
||
"type": "database"
|
||
}
|
||
```
|
||
|
||
#### Enterprise plugins
|
||
|
||
```json
|
||
{
|
||
"version": "0.16.0+ent",
|
||
"name": "vault-plugin-secrets-keymgmt",
|
||
"type": "secret"
|
||
}
|
||
```
|
||
|
||
### Sample payload using OCI image
|
||
|
||
```json
|
||
{
|
||
"sha256": "d150b9a0fbfddef9709d8ff92e5e6053ccd246b78632fc03b8548457026961a9",
|
||
"oci_image": "example-secret-plugin-oci-image",
|
||
"runtime": "example-runtime"
|
||
}
|
||
```
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin
|
||
```
|
||
|
||
## Read plugin
|
||
|
||
This endpoint returns the configuration data for the plugin with the given name.
|
||
|
||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||
any path-specific capabilities.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------------------------------------- |
|
||
| `GET` | `/sys/plugins/catalog/:type/:name?version=:version` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the plugin to retrieve.
|
||
This is part of the request URL.
|
||
|
||
- `type` `(string: <required>)` – Specifies the type of this plugin. May be
|
||
"auth", "database", or "secret".
|
||
|
||
- `version` `(string: "")` – The semantic version of the plugin to read. Required
|
||
if the plugin was registered with a version.
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request GET \
|
||
http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin?version=v1.0.0
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"args": [],
|
||
"builtin": false,
|
||
"runtime": "example-runtime",
|
||
"oci_image": "example-secret-plugin-oci-image",
|
||
"command": "/example-secret-plugin",
|
||
"name": "example-plugin",
|
||
"sha256": "0TC5oPv93vlwnY/5Ll5gU8zSRreGMvwDuFSEVwJpYek=",
|
||
"version": "v1.0.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Remove plugin from catalog
|
||
|
||
This endpoint removes the plugin with the given name.
|
||
|
||
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
|
||
any path-specific capabilities.
|
||
|
||
| Method | Path |
|
||
| :------- | :-------------------------------------------------- |
|
||
| `DELETE` | `/sys/plugins/catalog/:type/:name?version=:version` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the plugin to delete.
|
||
This is part of the request URL.
|
||
|
||
- `type` `(string: <required>)` – Specifies the type of this plugin. May be
|
||
"auth", "database", or "secret".
|
||
|
||
- `version` `(string: "")` – Specifies the semantic version of the plugin
|
||
to delete.
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin?version=v1.0.0
|
||
```
|