mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-22 15:11:07 +02:00
0660ea6fac
* Update README Let contributors know that docs will now be located in UDR * Add comments to each mdx doc Comment has been added to all mdx docs that are not partials * chore: added changelog changelog check failure * wip: removed changelog * Fix content errors * Doc spacing * Update website/content/docs/deploy/kubernetes/vso/helm.mdx Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
329 lines
9.6 KiB
Plaintext
329 lines
9.6 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: /sys/plugins/catalog - HTTP API
|
||
description: The `/sys/plugins/catalog` endpoint is used to manage plugins.
|
||
---
|
||
|
||
> [!IMPORTANT]
|
||
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.
|
||
|
||
# `/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. You can
|
||
omit version to register a plugin binary, but you must provide an
|
||
explicit version to register an extracted `.zip` file.
|
||
|
||
- `sha256` `(string: "")` – The SHA256 sum of a plugin binary or the OCI image.
|
||
Before Vault runs a plugin, it checks the plugin SHA against `sha256`. If the
|
||
actual SHA of the plugin binary and the SHA provided in `sha256` do not match,
|
||
Vault will not run the plugin. You must provide `sha256` to register a plugin
|
||
binary, but you must leave `sha256` unset to register an extracted `.zip` file.
|
||
|
||
- `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.
|
||
You must provide `command` to register a plugin binary. Vault ignores `command`
|
||
when you register with an extracted `.zip` file as it already knows the associated run command.
|
||
|
||
- `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"`.
|
||
|
||
- `download` `(bool: false)` - <EnterpriseAlert inline="true" /> **( BETA )**
|
||
Tells Vault to download the specified plugin from the
|
||
[HashiCorp releases page](https://releases.hashicorp.com/). Automatic
|
||
downloads only support secret and auth plugins with artifacts containing
|
||
`metadata.json` and `metadata.json.sig`. To use automatic downloads, your
|
||
network must permit HTTPS and TCP port 443 between all
|
||
Vault cluster nodes and `releases.hashicorp.com`.
|
||
|
||
|
||
### Sample payload
|
||
|
||
#### Community plugins
|
||
|
||
```json
|
||
{
|
||
"sha256": "d130b9a0fbfddef9709d8ff92e5e6053ccd246b78632fc03b8548457026961e9",
|
||
"command": "mysql-database-plugin",
|
||
"type": "database"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"version": "0.24.0",
|
||
"download": true
|
||
}
|
||
```
|
||
|
||
#### Enterprise plugins
|
||
|
||
```json
|
||
{
|
||
"version": "0.16.0+ent",
|
||
"name": "vault-plugin-secrets-keymgmt",
|
||
"type": "secret"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"version": "0.16.0+ent",
|
||
"download": true
|
||
}
|
||
```
|
||
|
||
### 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
|
||
```
|