scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-11-02 19:47:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Plugin versioning documentation (#17460)

Browse Source 
Co-authored-by: John-Michael Faircloth <fairclothjm@users.noreply.github.com>
This commit is contained in:
Tom Proctor
2022-10-11 23:12:02 +01:00
committed by GitHub
parent 11e7f1c624
commit 8bf0866164
15 changed files with 433 additions and 262 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
website/content/api-docs/secret/databases/index.mdx
View File

@@ -37,6 +37,9 @@ list of additional parameters.
- `plugin_name` `(string: <required>)` - Specifies the name of the plugin to use - `plugin_name` `(string: <required>)` - Specifies the name of the plugin to use
for this connection. for this connection.
- `plugin_version` `(string: "")` - Specifies the semantic version of the plugin
to use for this connection.
- `verify_connection` `(bool: true)` – Specifies if the connection is verified - `verify_connection` `(bool: true)` – Specifies if the connection is verified
during initial configuration. Defaults to true. during initial configuration. Defaults to true.
@@ -166,7 +169,10 @@ $ curl \
"connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/", "connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
"username": "vaultuser" "username": "vaultuser"
}, },
"plugin_name": "mysql-database-plugin" "password_policy": "",
"plugin_name": "mysql-database-plugin",
"plugin_version": "",
"root_credentials_rotate_statements": []
} }
} }
``` ```

82
website/content/api-docs/system/auth.mdx
View File

@@ -30,18 +30,52 @@ $ curl \
```json ```json
{ {
"request_id": "9bc0fab8-d65c-3961-afe6-d05f50c5fd22",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"github/": { "github/": {
"type": "github", "accessor": "auth_github_badd7fd0",
"description": "GitHub auth"
},
"token/": {
"config": { "config": {
"default_lease_ttl": 0, "default_lease_ttl": 0,
"max_lease_ttl": 0 "force_no_cache": false,
"max_lease_ttl": 0,
"token_type": "default-service"
},
"deprecation_status": "supported",
"description": "",
"external_entropy_access": false,
"local": false,
"options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false,
"type": "github",
"uuid": "4b42d1a4-0a0d-3c88-ae90-997e0c8b41be"
},
"token/": {
"accessor": "auth_token_bd90f507",
"config": {
"default_lease_ttl": 0,
"force_no_cache": false,
"max_lease_ttl": 0,
"token_type": "default-service"
}, },
"description": "token based credentials", "description": "token based credentials",
"type": "token" "external_entropy_access": false,
"local": false,
"options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false,
"type": "token",
"uuid": "e162baec-721b-7657-7913-c960df402f8a"
} }
},
"warnings": null
} }
``` ```
@@ -99,6 +133,11 @@ For example, enable the "foo" auth method will make it accessible at
- `allowed_response_headers` `(array: [])` - List of headers to whitelist, - `allowed_response_headers` `(array: [])` - List of headers to whitelist,
allowing a plugin to include them in the response. allowing a plugin to include them in the response.
- `plugin_version` `(string: "")` – Specifies the semantic version of the plugin
to use, e.g. "v1.0.0". If unspecified, the server will select any matching
unversioned plugin that may have been registered, the latest versioned plugin
registered, or a built-in plugin in that order of precendence.
Additionally, the following options are allowed in Vault open-source, but Additionally, the following options are allowed in Vault open-source, but
relevant functionality is only supported in Vault Enterprise: relevant functionality is only supported in Vault Enterprise:
@@ -146,8 +185,8 @@ $ curl \
This endpoints returns the configuration of the auth method at the given path. This endpoints returns the configuration of the auth method at the given path.
| Method | Path | | Method | Path |
| :----- | :--------------- | | :----- | :---------------- |
| `GET` | `/sys/auth/path` | | `GET` | `/sys/auth/:path` |
### Sample Request ### Sample Request
@@ -161,24 +200,10 @@ $ curl \
```json ```json
{ {
"uuid": "4b42d1a4-0a0d-3c88-ae90-997e0c8b41be",
"type": "github",
"accessor": "auth_github_badd7fd0",
"local": false,
"seal_wrap": false,
"external_entropy_access": false,
"options": null,
"config": {
"default_lease_ttl": 0,
"force_no_cache": false,
"max_lease_ttl": 0,
"token_type": "default-service"
},
"description": "",
"request_id": "8d2a1e33-4c00-46a5-f50d-4dc5f5d96f12", "request_id": "8d2a1e33-4c00-46a5-f50d-4dc5f5d96f12",
"lease_id": "", "lease_id": "",
"renewable": false,
"lease_duration": 0, "lease_duration": 0,
"renewable": false,
"data": { "data": {
"accessor": "auth_github_badd7fd0", "accessor": "auth_github_badd7fd0",
"config": { "config": {
@@ -187,17 +212,19 @@ $ curl \
"max_lease_ttl": 0, "max_lease_ttl": 0,
"token_type": "default-service" "token_type": "default-service"
}, },
"deprecation_status": "supported",
"description": "", "description": "",
"external_entropy_access": false, "external_entropy_access": false,
"local": false, "local": false,
"options": null, "options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false, "seal_wrap": false,
"type": "github", "type": "github",
"uuid": "4b42d1a4-0a0d-3c88-ae90-997e0c8b41be" "uuid": "4b42d1a4-0a0d-3c88-ae90-997e0c8b41be"
}, },
"wrap_info": null, "warnings": null
"warnings": null,
"auth": null
} }
``` ```
@@ -316,6 +343,9 @@ can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._
- `batch`: Override any auth method preference and always issue batch tokens - `batch`: Override any auth method preference and always issue batch tokens
from this mount from this mount
- `plugin_version` `(string: "")` – Specifies the semantic version of the plugin
to use, e.g. "v1.0.0". Changes will not take effect until the mount is reloaded.
### Sample Payload ### Sample Payload
```json ```json

24
website/content/api-docs/system/mounts.mdx
View File

@@ -44,6 +44,9 @@ $ curl \
"external_entropy_access": false, "external_entropy_access": false,
"local": true, "local": true,
"options": null, "options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false, "seal_wrap": false,
"type": "cubbyhole", "type": "cubbyhole",
"uuid": "79ddaa52-fa07-6f19-653a-f0777f6439fd" "uuid": "79ddaa52-fa07-6f19-653a-f0777f6439fd"
@@ -59,6 +62,9 @@ $ curl \
"external_entropy_access": false, "external_entropy_access": false,
"local": false, "local": false,
"options": null, "options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false, "seal_wrap": false,
"type": "identity", "type": "identity",
"uuid": "45f79a67-58f7-3f87-892c-9032084e7801" "uuid": "45f79a67-58f7-3f87-892c-9032084e7801"
@@ -70,12 +76,16 @@ $ curl \
"force_no_cache": false, "force_no_cache": false,
"max_lease_ttl": 0 "max_lease_ttl": 0
}, },
"deprecation_status": "supported",
"description": "key/value secret storage", "description": "key/value secret storage",
"external_entropy_access": false, "external_entropy_access": false,
"local": false, "local": false,
"options": { "options": {
"version": "2" "version": "2"
}, },
"plugin_version": "",
"running_plugin_version": "v0.13.0+builtin",
"running_sha256": "",
"seal_wrap": false, "seal_wrap": false,
"type": "kv", "type": "kv",
"uuid": "8074a73f-6921-c0cd-589a-016405dc46ec" "uuid": "8074a73f-6921-c0cd-589a-016405dc46ec"
@@ -92,6 +102,9 @@ $ curl \
"external_entropy_access": false, "external_entropy_access": false,
"local": false, "local": false,
"options": null, "options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false, "seal_wrap": false,
"type": "system", "type": "system",
"uuid": "c79f4f66-4cfa-4521-9d31-b1238b0a6800" "uuid": "c79f4f66-4cfa-4521-9d31-b1238b0a6800"
@@ -153,6 +166,11 @@ This endpoint enables a new secrets engine at the given path.
- `allowed_response_headers` `(array: [])` - List of headers to whitelist, - `allowed_response_headers` `(array: [])` - List of headers to whitelist,
allowing a plugin to include them in the response. allowing a plugin to include them in the response.
- `plugin_version` `(string: "")` – Specifies the semantic version of the plugin
to use, e.g. "v1.0.0". If unspecified, the server will select any matching
unversioned plugin that may have been registered, the latest versioned plugin
registered, or a built-in plugin in that order of precendence.
- `options` `(map<string|string>: nil)` - Specifies mount type specific options - `options` `(map<string|string>: nil)` - Specifies mount type specific options
that are passed to the backend. that are passed to the backend.
@@ -277,6 +295,9 @@ $ curl \
"external_entropy_access": false, "external_entropy_access": false,
"local": true, "local": true,
"options": null, "options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false, "seal_wrap": false,
"type": "cubbyhole", "type": "cubbyhole",
"uuid": "9c0e211a-904d-e41d-e1a2-7f1ff2bb8461" "uuid": "9c0e211a-904d-e41d-e1a2-7f1ff2bb8461"
@@ -355,6 +376,9 @@ This endpoint tunes configuration parameters for a given mount point.
- `allowed_managed_keys` `(array: [])` - List of managed key registry entry names - `allowed_managed_keys` `(array: [])` - List of managed key registry entry names
that the mount in question is allowed to access. that the mount in question is allowed to access.
- `plugin_version` `(string: "")` – Specifies the semantic version of the plugin
to use, e.g. "v1.0.0". Changes will not take effect until the mount is reloaded.
### Sample Payload ### Sample Payload
```json ```json

52
website/content/api-docs/system/plugins-catalog.mdx
View File

@@ -28,7 +28,7 @@ $ curl \
### Sample Response ### Sample Response
```javascript ```json
{ {
"data": { "data": {
"auth": [ "auth": [
@@ -44,6 +44,32 @@ $ curl \
"mysql-database-plugin", "mysql-database-plugin",
"postgresql-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"
},
...
],
"secret": [ "secret": [
"ad", "ad",
"aws", "aws",
@@ -76,7 +102,7 @@ $ curl \
### Sample Response ### Sample Response
```javascript ```json
{ {
"data": { "data": {
"keys": [ "keys": [
@@ -111,6 +137,8 @@ supplied name.
- `type` `(string: <required>)` – Specifies the type of this plugin. May be - `type` `(string: <required>)` – Specifies the type of this plugin. May be
"auth", "database", or "secret". "auth", "database", or "secret".
- `version` `(string: "")` - Specifies the semantic version of this plugin.
- `sha256` `(string: <required>)` – This is the SHA256 sum of the plugin's - `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. 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. they do not match the plugin can not be run.
@@ -153,8 +181,8 @@ This endpoint returns the configuration data for the plugin with the given name.
any path-specific capabilities. any path-specific capabilities.
| Method | Path | | Method | Path |
| :----- | :--------------------------------- | | :----- | :-------------------------------------------------- |
| `GET` | `/sys/plugins/catalog/:type/:name` | | `GET` | `/sys/plugins/catalog/:type/:name?version=:version` |
### Parameters ### Parameters
@@ -164,6 +192,8 @@ This endpoint returns the configuration data for the plugin with the given name.
- `type` `(string: <required>)` – Specifies the type of this plugin. May be - `type` `(string: <required>)` – Specifies the type of this plugin. May be
"auth", "database", or "secret". "auth", "database", or "secret".
- `version` `(string: "")` – The semantic version of the plugin to read.
### Sample Request ### Sample Request
```shell-session ```shell-session
@@ -175,14 +205,15 @@ $ curl \
### Sample Response ### Sample Response
```javascript ```json
{ {
"data": { "data": {
"args": [], "args": [],
"builtin": false, "builtin": false,
"command": "/tmp/vault-plugins/mysql-database-plugin", "command": "/tmp/vault-plugins/mysql-database-plugin",
"name": "example-plugin", "name": "example-plugin",
"sha256": "0TC5oPv93vlwnY/5Ll5gU8zSRreGMvwDuFSEVwJpYek=" "sha256": "0TC5oPv93vlwnY/5Ll5gU8zSRreGMvwDuFSEVwJpYek=",
"version": "v1.0.0"
} }
} }
``` ```
@@ -195,8 +226,8 @@ This endpoint removes the plugin with the given name.
any path-specific capabilities. any path-specific capabilities.
| Method | Path | | Method | Path |
| :------- | :--------------------------------- | | :------- | :-------------------------------------------------- |
| `DELETE` | `/sys/plugins/catalog/:type/:name` | | `DELETE` | `/sys/plugins/catalog/:type/:name?version=:version` |
### Parameters ### Parameters
@@ -206,11 +237,14 @@ This endpoint removes the plugin with the given name.
- `type` `(string: <required>)` – Specifies the type of this plugin. May be - `type` `(string: <required>)` – Specifies the type of this plugin. May be
"auth", "database", or "secret". "auth", "database", or "secret".
- `version` `(string: "")` – Specifies the semantic version of the plugin
to delete.
### Sample Request ### Sample Request
```shell-session ```shell-session
$ curl \ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request DELETE \ --request DELETE \
http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin?version=v1.0.0
``` ```

4
website/content/docs/commands/auth/enable.mdx
View File

@@ -88,3 +88,7 @@ flags](/docs/commands) included on all commands.
- `-token-type` `(string: "")` - Specifies the type of tokens that should be - `-token-type` `(string: "")` - Specifies the type of tokens that should be
returned by the auth method. returned by the auth method.
- `-plugin-version` `(string: "")` - Configures the semantic version of the plugin
to use. If unspecified, implies the built-in or any matching unversioned plugin
that may have been registered.

18
website/content/docs/commands/auth/list.mdx
View File

@@ -13,11 +13,25 @@ enabled auth methods and options for those methods.
## Deprecation Status Column ## Deprecation Status Column
As of 1.12, all builtin auth engines will have an associated Deprecation As of 1.12, all built-in auth engines will have an associated Deprecation
Status. This status will be reflected in the `Deprecation Status` column, seen Status. This status will be reflected in the `Deprecation Status` column, seen
below. All auth engines which are not provided by builtin plugins will show a below. All auth engines which are not provided by built-in plugins will show a
`Deprecation Status` of "n/a". `Deprecation Status` of "n/a".
## Version Columns
The `-detailed` view displays some version information for each mount.
The Version field indicates the configured version for the plugin. Empty, or "n/a",
indicates the built-in or any matching unversioned plugin that may have been registered.
Running Version indicates the actual plugin version running, which may differ from
Version if the plugin hasn't been reloaded since the configured version was updated
using the `secrets tune` command. Finally, the Running SHA256 field indicates the
SHA256 sum of the running plugin's binary. This may be different from the SHA256
registered in the catalog if the plugin hasn't been reloaded since the plugin
version was overwritten in the catalog.
## Examples ## Examples
List all auth methods: List all auth methods:

4
website/content/docs/commands/auth/tune.mdx
View File

@@ -83,3 +83,7 @@ flags](/docs/commands) included on all commands.
- `-token-type` `(string: "")` - Specifies the type of tokens that should be - `-token-type` `(string: "")` - Specifies the type of tokens that should be
returned by the auth method. returned by the auth method.
- `-plugin-version` `(string: "")` - Configures the semantic version of the plugin
to use. The new version will not start running until the mount is
[reloaded](/docs/commands/plugin/reload).

26
website/content/docs/commands/plugin/index.mdx
View File

@@ -13,35 +13,40 @@ the plugin catalog
## Examples ## Examples
List all available plugins in the catalog: List all available secret plugins in the catalog:
```shell-session ```shell-session
$ vault plugin list $ vault plugin list secret
Plugins Name Version
------- ---- -------
my-custom-plugin ad v0.14.0+builtin
# ... alicloud v0.13.0+builtin
...
``` ```
Register a new plugin to the catalog: Register a new secret plugin to the catalog:
```shell-session ```shell-session
$ vault plugin register \ $ vault plugin register \
-sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \ -sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
my-custom-plugin secret my-custom-plugin
Success! Registered plugin: my-custom-plugin Success! Registered plugin: my-custom-plugin
``` ```
Get information about a plugin in the catalog: Get information about a plugin in the catalog:
```shell-session ```shell-session
$ vault plugin info my-custom-plugin $ vault plugin info secret my-custom-plugin
Key Value Key Value
--- ----- --- -----
args []
builtin false
command my-custom-plugin command my-custom-plugin
deprecation_status n/a
name my-custom-plugin name my-custom-plugin
sha256 d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 sha256 33e72f3d30ff2acdbf3cf3c8fa1c8945b60dab876c4226ab25617a63c9f16cc5
version n/a
``` ```
## Usage ## Usage
@@ -57,6 +62,7 @@ Subcommands:
list Lists available plugins list Lists available plugins
register Registers a new plugin in the catalog register Registers a new plugin in the catalog
reload Reload mounted plugin backend reload Reload mounted plugin backend
reload-status Get the status of an active or recently completed global plugin reload
``` ```
For more information, examples, and usage about a subcommand, click on the name For more information, examples, and usage about a subcommand, click on the name

12
website/content/docs/commands/plugin/info.mdx
View File

@@ -20,7 +20,7 @@ pair, seen below.
Display information about a plugin Display information about a plugin
```shell-session ```shell-session
$ vault plugin info auth my-custom-plugin $ vault plugin info -version=v1.0.0 auth my-custom-plugin
Key Value Key Value
--- ----- --- -----
@@ -29,7 +29,8 @@ builtin false
command my-custom-plugin command my-custom-plugin
deprecation_status n/a deprecation_status n/a
name my-custom-plugin name my-custom-plugin
sha256 d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 sha256 04ce575260fa3a2cfc477d13ac327108c50838a03917ec4d6df38ecdc64452d1
version v1.0.0
``` ```
```shell-session ```shell-session
@@ -42,6 +43,7 @@ command n/a
deprecation_status supported deprecation_status supported
name postgresql-database-plugin name postgresql-database-plugin
sha256 n/a sha256 n/a
version n/a
``` ```
## Usage ## Usage
@@ -59,3 +61,9 @@ flags](/docs/commands) included on all commands.
- `-format` `(string: "table")` - Print the output in the given format. Valid - `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the formats are "table", "json", or "yaml". This can also be specified via the
`VAULT_FORMAT` environment variable. `VAULT_FORMAT` environment variable.
### Command Options
- `-plugin-version` `(string: "")` - Semantic version of the plugin to read from
the catalog. If unspecified, refers to the unversioned plugin registered with
the same name and type, or the built-in plugin, in that order of precedence.

4
website/content/docs/commands/plugin/register.mdx
View File

@@ -51,3 +51,7 @@ flags](/docs/commands) included on all commands.
- `-command` `(string: "")` - Name of the command to run to invoke the binary. - `-command` `(string: "")` - Name of the command to run to invoke the binary.
By default, this is the name of the plugin. By default, this is the name of the plugin.
- `-plugin-version` `(string: "")` - Semantic version of the plugin to run from
the catalog. If unspecified, refers to the unversioned plugin registered with
the same name and type, or the built-in plugin, in that order of precedence.

4
website/content/docs/commands/secrets/enable.mdx
View File

@@ -107,3 +107,7 @@ flags](/docs/commands) included on all commands.
in question is allowed to access. Note that multiple keys may be specified in question is allowed to access. Note that multiple keys may be specified
either by providing the key names as a comma separated string or by providing either by providing the key names as a comma separated string or by providing
this option multiple times, each time with 1 key. this option multiple times, each time with 1 key.
- `-plugin-version` `(string: "")` - Configures the semantic version of the plugin
to use. If unspecified, implies the built-in or any matching unversioned plugin
that may have been registered.

40
website/content/docs/commands/secrets/list.mdx
View File

@@ -17,34 +17,48 @@ that the system default is in use.
## Deprecation Status Column ## Deprecation Status Column
As of 1.12, all builtin secrets engines will have an associated Deprecation As of 1.12, all built-in secrets engines will have an associated Deprecation
Status. This status will be reflected in the `Deprecation Status` column, seen Status. This status will be reflected in the `Deprecation Status` column, seen
below. All secrets engines which are not provided by builtin plugins will show a below. All secrets engines which are not provided by built-in plugins will show a
`Deprecation Status` of "n/a". `Deprecation Status` of "n/a".
## Version Columns
The `-detailed` view displays some version information for each mount.
The Version field indicates the configured version for the plugin. Empty, or "n/a",
indicates the built-in or any matching unversioned plugin that may have been registered.
Running Version indicates the actual plugin version running, which may differ from
Version if the plugin hasn't been reloaded since the configured version was updated
using the `secrets tune` command. Finally, the Running SHA256 field indicates the
SHA256 sum of the running plugin's binary. This may be different from the SHA256
registered in the catalog if the plugin hasn't been reloaded since the plugin
version was overwritten in the catalog.
## Examples ## Examples
List all enabled secrets engines: List all enabled secrets engines:
```shell-session ```shell-session
$ vault secrets list $ vault secrets list
Path Type Description Path Type Accessor Description
---- ---- ----------- ---- ---- -------- -----------
cubbyhole/ cubbyhole per-token private secret storage cubbyhole/ cubbyhole cubbyhole_548b4dc5 per-token private secret storage
secret/ kv key/value secret storage secret/ kv identity_aa00c06d key/value secret storage
sys/ system system endpoints used for control, policy and debugging sys/ system system_547412e3 system endpoints used for control, policy and debugging
``` ```
List all enabled secrets engines with detailed output: List all enabled secrets engines with detailed output:
```shell-session ```shell-session
$ vault secrets list -detailed $ vault secrets list -detailed
Path Plugin Accessor Default TTL Max TTL Force No Cache Replication Seal Wrap External Entropy Access Options Description UUID Deprecation Status Path Plugin Accessor Default TTL Max TTL Force No Cache Replication Seal Wrap External Entropy Access Options Description UUID Version Running Version Running SHA256 Deprecation Status
---- ------ -------- ----------- ------- -------------- ----------- --------- ----------------------- ------- ----------- ---- ------------------ ---- ------ -------- ----------- ------- -------------- ----------- --------- ----------------------- ------- ----------- ---- ------- --------------- -------------- ------------------
cubbyhole/ cubbyhole cubbyhole_b16d1bc0 n/a n/a false local false false map[] per-token private secret storage 8c64d56b-9d46-d667-1155-a8c1a83a5d01 n/a cubbyhole/ cubbyhole cubbyhole_b16d1bc0 n/a n/a false local false false map[] per-token private secret storage 8c64d56b-9d46-d667-1155-a8c1a83a5d01 n/a v1.12.0+builtin.vault n/a n/a
identity/ identity identity_3d67c936 system system false replicated false false map[] identity store 5aa1e59c-33b5-9dec-05d6-c80c9a800557 n/a identity/ identity identity_3d67c936 system system false replicated false false map[] identity store 5aa1e59c-33b5-9dec-05d6-c80c9a800557 n/a v1.12.0+builtin.vault n/a n/a
postgresql/ postgresql postgresql_f0a54308 system system false replicated false false map[] n/a 8cdc1d2d-0713-eaa6-17e3-49790a60650b deprecated postgresql/ postgresql postgresql_f0a54308 system system false replicated false false map[] n/a 8cdc1d2d-0713-eaa6-17e3-49790a60650b n/a v1.12.0+builtin.vault n/a deprecated
sys/ system system_c86bd362 n/a n/a false replicated true false map[] system endpoints used for control, policy and debugging e3193999-0875-d38d-3458-21d9f2762c80 n/a sys/ system system_c86bd362 n/a n/a false replicated true false map[] system endpoints used for control, policy and debugging e3193999-0875-d38d-3458-21d9f2762c80 n/a v1.12.0+builtin.vault n/a n/a
``` ```
## Usage ## Usage

4
website/content/docs/commands/secrets/tune.mdx
View File

@@ -93,3 +93,7 @@ flags](/docs/commands) included on all commands.
in question is allowed to access. Note that multiple keys may be specified in question is allowed to access. Note that multiple keys may be specified
either by providing the key names as a comma separated string or by providing either by providing the key names as a comma separated string or by providing
this option multiple times, each time with 1 key. this option multiple times, each time with 1 key.
- `-plugin-version` `(string: "")` - Configures the semantic version of the plugin
to use. The new version will not start running until the mount is
[reloaded](/docs/commands/plugin/reload).

73
website/content/docs/plugins/index.mdx
View File

@@ -7,21 +7,24 @@ description: Learn about Vault's plugin system.
# Plugin System # Plugin System
All Vault auth methods and secrets engines are considered plugins. This concept Vault supports 3 types of plugins; auth methods, secret engines, and database
allows both built-in and external plugins to be treated like building blocks. plugins. This concept allows both built-in and external plugins to be treated
Any plugin can exist at multiple different mount paths. Different versions of a like building blocks. Any plugin can exist at multiple different mount paths.
plugin may be at each location, with each version differing from Vault's Different versions of a plugin may be at each location, with each version differing
version. from Vault's version.
A plugin is uniquely identified by its type (one of `secret`, `auth`, or
`database`), name (e.g. `aws`), and version (e.g `v1.0.0`). An empty version
implies either the built-in plugin or the single unversioned plugin that can
be registered.
See [Plugin Upgrade Procedure](/docs/upgrading/plugins#plugin-upgrade-procedure)
for details on how to upgrade a built-in plugin in-place.
## Built-In Plugins ## Built-In Plugins
Built-in plugins are shipped with Vault, often for commonly used implementations, Built-in plugins are shipped with Vault, often for commonly used integrations,
and require no additional operator intervention to run. Built-in plugins are and can be used without any prerequisite steps.
just like any other backend code inside Vault.
To use a different or edited version of a built-in plugin, the plugin must be
run as an external plugin. See [Overriding Built-in Plugins](/docs/upgrading/plugins#overriding-built-in-plugins)
for details on how to override a built-in plugin in-place.
## External Plugins ## External Plugins
@@ -33,8 +36,48 @@ binaries can be obtained from [releases.hashicorp.com](https://releases.hashicor
or they can be [built from source](/docs/plugins/plugin-development#building-a-plugin-from-source). or they can be [built from source](/docs/plugins/plugin-development#building-a-plugin-from-source).
Vault's external plugins are completely separate, standalone applications that Vault's external plugins are completely separate, standalone applications that
Vault executes and communicates with over RPC. Each time a Vault secret engine Vault executes and communicates with over RPC. Each time a Vault secret engine,
or auth method is mounted, a new process is spawned. However, plugins can be auth method, or database plugin is mounted, a new process is spawned. However,
made to implement [plugin multiplexing](/docs/plugins/plugin-architecture#plugin-multiplexing) plugins can be made to implement [plugin multiplexing](/docs/plugins/plugin-architecture#plugin-multiplexing)
to improve performance. Plugin multiplexing allows plugin processes to be to improve performance. Plugin multiplexing allows plugin processes to be
reused across all mounts of a given type. reused across all mounts of a given type.
## Plugin Versioning
Vault supports managing, running and upgrading plugins using semantic version
information.
The plugin catalog optionally supports specifying a semantic version when
registering an external plugin. Multiple versions of a plugin can be registered
in the catalog simultaneously, and a version can be selected when mounting a
plugin or tuning an existing mount in-place.
If no version is specified when creating a new mount, the following precedence is used
for any available plugins whose type and name match:
* The plugin registered with no version
* The plugin with the most recent semantic version among any registered versions
* The plugin built into Vault
### Built-In Versions
Vault will report a version for built-in plugins to indicate what version of the
plugin code got built into Vault as a dependency. For example:
```shell-session
$ vault plugin list secret
Name Version
---- -------
ad v0.14.0+builtin
alicloud v0.13.0+builtin
aws v1.12.0+builtin.vault
# ...
```
Here, Vault has a dependency on `v0.14.0` of the [hashicorp/vault-plugin-secrets-ad](https://github.com/hashicorp/vault-plugin-secrets-ad)
repo, and the `vault` metadata identifier for `aws` indicates that plugin's code was
within the Vault repo. For plugins within the Vault repo, Vault's own major, minor,
and patch versions are used to form the plugin version.
The `builtin` metadata identifier is reserved and cannot be used when registering
external plugins.

294
website/content/docs/upgrading/plugins.mdx
View File

@@ -6,58 +6,76 @@ description: These are general upgrade instructions for Vault plugins.
# Upgrading Vault Plugins # Upgrading Vault Plugins
## External Plugin Upgrade Procedure ## Plugin Upgrade Procedure
The following procedure details steps for upgrading an external plugin that has The following procedures detail steps for upgrading a plugin that has been mounted
been registered to the catalog on a running server. This procedure is at a path on a running server. The steps are the same whether the plugin being
applicable to secret engines, auth methods, and database plugins. upgraded is built-in or external.
Vault executes plugin binaries when they are configured and roles are established ~> Plugin versioning was introduced with Vault 1.12.0, so if your Vault server is
around them. The binary cannot be modified or replaced while running, so on 1.11.x or earlier, see the [1.11.x version of this page](/docs/v1.11.x/upgrading/plugins)
upgrades cannot be performed by simply swapping the binary and updating the hash for plugin upgrade instructions.
in the plugin catalog.
Instead, you can restart or reload a plugin with the ### Upgrading auth and secrets plugins
`sys/plugins/reload/backend` [API][plugin_reload_api]. Follow these steps to
replace or upgrade a Vault plugin binary:
1. [Register][plugin_registration] version 1 of `my-db-plugin` to the catalog. The process is nearly identical for auth and secret plugins. If you are upgrading
Skip this step if your plugin is already registered. an auth plugin, just replace all usages of `secrets` or `secret` with `auth`.
1. [Register][plugin_registration] the first version of your plugin to the catalog.
Skip this step if your initial plugin is built-in or already registered.
```shell-session ```shell-session
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \ $ vault plugin register
database \ # type -sha256=<SHA256 Hex value of the plugin binary> \
my-db-plugin secret \
my-secret-plugin
``` ```
2. [Mount][plugin_management] the plugin backend. Skip this step if the backend 1. [Mount][plugin_management] the plugin. Skip this step if your initial plugin
is already mounted. is already mounted.
```shell-session ```shell-session
$ vault secrets enable database $ vault secrets enable my-secret-plugin
``` ```
3. Register version 2 of `my-db-plugin` to the catalog under the same plugin 1. Register a second version of your plugin. You **must** use the same plugin
name, but with updated command to run version 2 of `my-db-plugin` and updated type and name (the last two arguments) as the plugin being upgraded. This is
sha256 of the new binary true regardless of whether the plugin being upgraded is built-in or external.
```shell-session ```shell-session
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \ $ vault plugin register \
database \ # type -sha256=<SHA256 Hex value of the plugin binary> \
my-db-plugin -command=my-secret-plugin-1.0.1 \
-version=v1.0.1 \
secret \
my-secret-plugin
``` ```
4. Trigger a [plugin reload](/docs/commands/plugin/reload) to reload all 1. Tune the existing mount to configure it to use the newly registered version.
```shell-session
$ vault secrets tune -plugin-version=v1.0.1 my-secret-plugin
```
1. If you wish, you can check the updated configuration. Notice the "Version" is
now different from the "Running Version".
```shell-session
$ vault secrets list -detailed
```
1. Finally, trigger a [plugin reload](/docs/commands/plugin/reload) to reload all
mounted backends using that plugin or a subset of the mounts using that plugin mounted backends using that plugin or a subset of the mounts using that plugin
with either the `plugin` or `mounts` parameter respectively. with either the `plugin` or `mounts` flag respectively.
```shell-session ```shell-session
$ vault plugin reload -plugin my-db-plugin $ vault plugin reload -plugin my-secret-plugin
``` ```
Until step 4, the mount will still use version 1 of `my-db-plugin`, and when Until the last step, the mount will still run the first version of `my-secret-plugin`. When
the reload is triggered, Vault will kill `my-db-plugin`’s process and start the the reload is triggered, Vault will kill `my-secret-plugin`’s process and start the
new plugin process for `my-db-plugin` version 2. new plugin process for `my-secret-plugin` version 1.0.1. The "Running Version" should also
now match the "Version" when you run `vault secrets list -detailed`.
-> **Important:** Plugin reload of a new plugin binary must be -> **Important:** Plugin reload of a new plugin binary must be
performed on each Vault instance. Performing a plugin upgrade on a single performed on each Vault instance. Performing a plugin upgrade on a single
@@ -65,147 +83,101 @@ instance or through a load balancer can result in mismatched
plugin binaries within a cluster. On a replicated cluster this may be accomplished plugin binaries within a cluster. On a replicated cluster this may be accomplished
by setting the 'scope' parameter of the reload to 'global'. by setting the 'scope' parameter of the reload to 'global'.
## Overriding Built-in Plugins ### Upgrading database plugins
### Background 1. [Register][plugin_registration] the first version of your plugin to the catalog.
Skip this step if your initial plugin is built-in or already registered.
Vault's auth methods and secrets engines are structured as plugins, but this ```shell-session
design is not obvious since many of them are built into Vault. $ vault plugin register
-sha256=<SHA256 Hex value of the plugin binary> \
database \
my-db-plugin
```
You can see them with the Vault plugin list command, for example, the list of 1. [Mount][plugin_management] the plugin. Skip this step if your initial plugin
Secrets engines: is already mounted.
```shell-session
$ vault secrets enable database
$ vault write database/config/my-db \
plugin_name=my-db-plugin \
# ...
```
1. Register a second version of your plugin. You **must** use the same plugin
type and name (the last two arguments) as the plugin being upgraded. This is
true regardless of whether the plugin being upgraded is built-in or external.
```shell-session
$ vault plugin register \
-sha256=<SHA256 Hex value of the plugin binary> \
-command=my-db-plugin-1.0.1 \
-version=v1.0.1 \
database \
my-db-plugin
```
1. Update the database config with the new version. The database secrets
engine will immediately reload the plugin, using the new version. Any omitted
config parameters will not be updated.
```shell-session
$ vault write database/config/my-db \
plugin_version=v1.0.1
```
Until the last step, the mount will still run the first version of `my-db-plugin`. When
the reload is triggered, Vault will kill `my-db-plugin`’s process and start the
new plugin process for `my-db-plugin` version 1.0.1.
### Downgrading Plugins
Plugin downgrades follow the same procedure as upgrades. You can use the Vault
plugin list command to check what plugin versions are available to downgrade to:
```shell-session ```shell-session
$ vault plugin list secret $ vault plugin list secret
Plugins Name Version
------- ---- -------
ad ad v0.14.0+builtin
alicloud alicloud v0.13.0+builtin
aws aws v1.12.0+builtin.vault
azure azure v0.14.0+builtin
cassandra cassandra v1.12.0+builtin.vault
consul consul v1.12.0+builtin.vault
gcp gcp v0.14.0+builtin
gcpkms gcpkms v0.13.0+builtin
kv kv v0.13.3+builtin
ldap ldap v1.12.0+builtin.vault
mongodb mongodb v1.12.0+builtin.vault
mongodbatlas mongodbatlas v0.8.0+builtin
mssql mssql v1.12.0+builtin.vault
mysql mysql v1.12.0+builtin.vault
nomad nomad v1.12.0+builtin.vault
openldap openldap v0.9.0+builtin
pki pki v1.12.0+builtin.vault
postgresql postgresql v1.12.0+builtin.vault
rabbitmq rabbitmq v1.12.0+builtin.vault
ssh ssh v1.12.0+builtin.vault
terraform terraform v0.6.0+builtin
totp totp v1.12.0+builtin.vault
transit transit v1.12.0+builtin.vault
``` ```
This will list all Secrets engines, internal (built-in) or external. To find ### Additional Upgrade Notes
out if a plugin is built-in, we can query its info:
```shell-session
$ vault plugin info secret azure
Key Value
--- -----
args []
builtin true
command n/a
name azure
sha256 n/a
```
Because these built-in engines are plugins, they can be overridden. This can be
a useful way to leverage features or bug fixes in plugins that are newer than
the version of Vault you're using, without updating or even restarting Vault,
and while retaining the data for your existing mount.
Assume you have a new version of Azure Secrets and the binary is called
"azure_new". The binary needs to be in the [plugin directory](/docs/plugins/plugin-architecture#plugin-directory)
and can then be registered as either a distinct plugin, or overriding the
current one.
~> **Important:** do not disable (`vault secrets disable ...`) any mount that has
data you're interested in; that would erase storage. For the in-place update,
register a new plugin atop the built-in one and leave any mounts alone.
### Procedure for Overriding Built-in Plugins
The syntax is the same as an external plugin, with the difference being you
name it the same as a built-in:
```shell-session
$ vault plugin register \
-sha256=<SHA256 Hex value of the plugin binary> \
-command=azure_new \
secret \
azure
```
"-command=azure_new" is the name of the binary, "secret" is the plugin type,
and "azure" is the name of the built-in plugin that we're overriding. We can
verify that the override is in place:
```shell-session
$ vault plugin info secret azure
Key Value
--- -----
args []
builtin false
command azure_new
name azure
sha256 f6f6ec45d37484c257aa9ff80444b9f244aaef1c650edf8a42a2a1d3f00db2c5
```
At this point we've overridden the built-in, but it is not yet actively
handling requests. For that we run:
```shell-session
$ vault plugin reload -plugin=azure
```
### Procedure for Reverting After Overriding A Built-in Plugin
To revert the override, first deregister the plugin:
```shell-session
$ vault plugin deregister secret azure
```
Next, verify the override has been reverted and we are now using the built-in
plugin:
```shell-session
$ vault plugin info secret azure
Key Value
--- -----
args []
builtin true
command n/a
name azure
sha256 n/a
```
Finally, reload the plugin:
```shell-session
$ vault plugin reload -plugin=azure
```
### Caveats to Overriding Built-in Plugins
* As mentioned earlier, disabling existing mounts will wipe the existing data. * As mentioned earlier, disabling existing mounts will wipe the existing data.
* This type of upgrade affects all uses of the plugin. So if you have 5 * Overwriting an existing version in the catalog will affect all uses of that
different Azure Secrets mounts, they'll all change after the replacement. If plugin version. So if you have 5 different Azure Secrets mounts using v1.0.0,
you don't want that, you'll need to register the plugin under a different name they'll all start using the new binary if you overwrite it. We recommend
and start with a fresh mount. treating plugin versions in the catalog as immutable, much like version control
* In most cases, data upgrade and downgrade is not an issue. If the "new" version tags.
introduces new data and you downgrade, the "old" version will ignore the * Each plugin has its own data within Vault storage. While it is rare for HashiCorp
extraneous data. In some cases upgrading changes existing data in non-backwards maintained plugins to update their storage schema, it is up to plugin authors
compatible ways, so it is good to check whether this is an issue. to manage schema upgrades and downgrades. Check the plugin release notes for
any unsupported upgrade or downgrade transitions, especially before moving to
a new major version or downgrading.
[plugin_reload_api]: /api-docs/system/plugins-reload-backend [plugin_reload_api]: /api-docs/system/plugins-reload-backend
[plugin_registration]: /docs/plugins/plugin-architecture#plugin-registration [plugin_registration]: /docs/plugins/plugin-architecture#plugin-registration