luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases 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 ee85f0098a
commit 918ce6f90e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 433 additions and 262 deletions
Show stats 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
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
during initial configuration. Defaults to true.
@ -166,7 +169,10 @@ $ curl \
"connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
"username": "vaultuser"
},
"plugin_name": "mysql-database-plugin"
"password_policy": "",
"plugin_name": "mysql-database-plugin",
"plugin_version": "",
"root_credentials_rotate_statements": []
}
}
```

94
website/content/api-docs/system/auth.mdx
View file

@ -30,18 +30,52 @@ $ curl \
```json
{
"github/": {
"type": "github",
"description": "GitHub auth"
},
"token/": {
"config": {
"default_lease_ttl": 0,
"max_lease_ttl": 0
"request_id": "9bc0fab8-d65c-3961-afe6-d05f50c5fd22",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"github/": {
"accessor": "auth_github_badd7fd0",
"config": {
"default_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"
},
"description": "token based credentials",
"type": "token"
}
"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",
"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,
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
relevant functionality is only supported in Vault Enterprise:
@ -145,9 +184,9 @@ $ curl \
This endpoints returns the configuration of the auth method at the given path.
| Method | Path |
| :----- | :--------------- |
| `GET` | `/sys/auth/path` |
| Method | Path |
| :----- | :---------------- |
| `GET` | `/sys/auth/:path` |
### Sample Request
@ -161,24 +200,10 @@ $ curl \
```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",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"renewable": false,
"data": {
"accessor": "auth_github_badd7fd0",
"config": {
@ -187,17 +212,19 @@ $ curl \
"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"
},
"wrap_info": null,
"warnings": null,
"auth": null
"warnings": 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
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
```json

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

@ -44,6 +44,9 @@ $ curl \
"external_entropy_access": false,
"local": true,
"options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false,
"type": "cubbyhole",
"uuid": "79ddaa52-fa07-6f19-653a-f0777f6439fd"
@ -59,6 +62,9 @@ $ curl \
"external_entropy_access": false,
"local": false,
"options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false,
"type": "identity",
"uuid": "45f79a67-58f7-3f87-892c-9032084e7801"
@ -70,12 +76,16 @@ $ curl \
"force_no_cache": false,
"max_lease_ttl": 0
},
"deprecation_status": "supported",
"description": "key/value secret storage",
"external_entropy_access": false,
"local": false,
"options": {
"version": "2"
},
"plugin_version": "",
"running_plugin_version": "v0.13.0+builtin",
"running_sha256": "",
"seal_wrap": false,
"type": "kv",
"uuid": "8074a73f-6921-c0cd-589a-016405dc46ec"
@ -92,6 +102,9 @@ $ curl \
"external_entropy_access": false,
"local": false,
"options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false,
"type": "system",
"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,
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
that are passed to the backend.
@ -277,6 +295,9 @@ $ curl \
"external_entropy_access": false,
"local": true,
"options": null,
"plugin_version": "",
"running_plugin_version": "v1.12.0+builtin.vault",
"running_sha256": "",
"seal_wrap": false,
"type": "cubbyhole",
"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
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
```json

68
website/content/api-docs/system/plugins-catalog.mdx
View file

@ -28,7 +28,7 @@ $ curl \
### Sample Response
```javascript
```json
{
"data": {
"auth": [
@ -44,6 +44,32 @@ $ curl \
"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"
},
...
],
"secret": [
"ad",
"aws",
@ -76,7 +102,7 @@ $ curl \
### Sample Response
```javascript
```json
{
"data": {
"keys": [
@ -111,6 +137,8 @@ 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.
- `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.
@ -152,9 +180,9 @@ 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` |
| Method | Path |
| :----- | :-------------------------------------------------- |
| `GET` | `/sys/plugins/catalog/:type/:name?version=:version` |
### 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
"auth", "database", or "secret".
- `version` `(string: "")` – The semantic version of the plugin to read.
### Sample Request
```shell-session
@ -175,15 +205,16 @@ $ curl \
### Sample Response
```javascript
```json
{
"data": {
"args": [],
"builtin": false,
"command": "/tmp/vault-plugins/mysql-database-plugin",
"name": "example-plugin",
"sha256": "0TC5oPv93vlwnY/5Ll5gU8zSRreGMvwDuFSEVwJpYek="
}
"data": {
"args": [],
"builtin": false,
"command": "/tmp/vault-plugins/mysql-database-plugin",
"name": "example-plugin",
"sha256": "0TC5oPv93vlwnY/5Ll5gU8zSRreGMvwDuFSEVwJpYek=",
"version": "v1.0.0"
}
}
```
@ -194,9 +225,9 @@ 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` |
| Method | Path |
| :------- | :-------------------------------------------------- |
| `DELETE` | `/sys/plugins/catalog/:type/:name?version=:version` |
### 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
"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
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
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
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
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".
## 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
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
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).

44
website/content/docs/commands/plugin/index.mdx
View file

@ -13,35 +13,40 @@ the plugin catalog
## Examples
List all available plugins in the catalog:
List all available secret plugins in the catalog:
```shell-session
$ vault plugin list
$ vault plugin list secret
Plugins
-------
my-custom-plugin
# ...
Name Version
---- -------
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
$ vault plugin register \
-sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
my-custom-plugin
secret my-custom-plugin
Success! Registered plugin: my-custom-plugin
```
Get information about a plugin in the catalog:
```shell-session
$ vault plugin info my-custom-plugin
Key Value
--- -----
command my-custom-plugin
name my-custom-plugin
sha256 d3f0a8be02f6c074cf38c9c99d4d04c9c6466249
$ vault plugin info secret my-custom-plugin
Key Value
--- -----
args []
builtin false
command my-custom-plugin
deprecation_status n/a
name my-custom-plugin
sha256 33e72f3d30ff2acdbf3cf3c8fa1c8945b60dab876c4226ab25617a63c9f16cc5
version n/a
```
## Usage
@ -52,11 +57,12 @@ Usage: vault plugin <subcommand> [options] [args]
# ...
Subcommands:
deregister Deregister an existing plugin in the catalog
info Read information about a plugin in the catalog
list Lists available plugins
register Registers a new plugin in the catalog
reload Reload mounted plugin backend
deregister Deregister an existing plugin in the catalog
info Read information about a plugin in the catalog
list Lists available plugins
register Registers a new plugin in the catalog
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

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

@ -20,7 +20,7 @@ pair, seen below.
Display information about a plugin
```shell-session
$ vault plugin info auth my-custom-plugin
$ vault plugin info -version=v1.0.0 auth my-custom-plugin
Key Value
--- -----
@ -29,7 +29,8 @@ builtin false
command my-custom-plugin
deprecation_status n/a
name my-custom-plugin
sha256 d3f0a8be02f6c074cf38c9c99d4d04c9c6466249
sha256 04ce575260fa3a2cfc477d13ac327108c50838a03917ec4d6df38ecdc64452d1
version v1.0.0
```
```shell-session
@ -42,6 +43,7 @@ command n/a
deprecation_status supported
name postgresql-database-plugin
sha256 n/a
version n/a
```
## Usage
@ -59,3 +61,9 @@ flags](/docs/commands) included on all commands.
- `-format` `(string: "table")` - Print the output in the given format. Valid
formats are "table", "json", or "yaml". This can also be specified via the
`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.
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
either by providing the key names as a comma separated string or by providing
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
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
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".
## 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
List all enabled secrets engines:
```shell-session
$ vault secrets list
Path Type Description
---- ---- -----------
cubbyhole/ cubbyhole per-token private secret storage
secret/ kv key/value secret storage
sys/ system system endpoints used for control, policy and debugging
Path Type Accessor Description
---- ---- -------- -----------
cubbyhole/ cubbyhole cubbyhole_548b4dc5 per-token private secret storage
secret/ kv identity_aa00c06d key/value secret storage
sys/ system system_547412e3 system endpoints used for control, policy and debugging
```
List all enabled secrets engines with detailed output:
```shell-session
$ 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
---- ------ -------- ----------- ------- -------------- ----------- --------- ----------------------- ------- ----------- ---- ------------------
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
identity/ identity identity_3d67c936 system system false replicated false false map[] identity store 5aa1e59c-33b5-9dec-05d6-c80c9a800557 n/a
postgresql/ postgresql postgresql_f0a54308 system system false replicated false false map[] n/a 8cdc1d2d-0713-eaa6-17e3-49790a60650b 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
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 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 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 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 v1.12.0+builtin.vault n/a n/a
```
## 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
either by providing the key names as a comma separated string or by providing
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
All Vault auth methods and secrets engines are considered plugins. This concept
allows both built-in and external plugins to be treated like building blocks.
Any plugin can exist at multiple different mount paths. Different versions of a
plugin may be at each location, with each version differing from Vault's
version.
Vault supports 3 types of plugins; auth methods, secret engines, and database
plugins. This concept allows both built-in and external plugins to be treated
like building blocks. Any plugin can exist at multiple different mount paths.
Different versions of a plugin may be at each location, with each version differing
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 are shipped with Vault, often for commonly used implementations,
and require no additional operator intervention to run. Built-in plugins are
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.
Built-in plugins are shipped with Vault, often for commonly used integrations,
and can be used without any prerequisite steps.
## 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).
Vault's external plugins are completely separate, standalone applications that
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
made to implement [plugin multiplexing](/docs/plugins/plugin-architecture#plugin-multiplexing)
Vault executes and communicates with over RPC. Each time a Vault secret engine,
auth method, or database plugin is mounted, a new process is spawned. However,
plugins can be made to implement [plugin multiplexing](/docs/plugins/plugin-architecture#plugin-multiplexing)
to improve performance. Plugin multiplexing allows plugin processes to be
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
## External Plugin Upgrade Procedure
## Plugin Upgrade Procedure
The following procedure details steps for upgrading an external plugin that has
been registered to the catalog on a running server. This procedure is
applicable to secret engines, auth methods, and database plugins.
The following procedures detail steps for upgrading a plugin that has been mounted
at a path on a running server. The steps are the same whether the plugin being
upgraded is built-in or external.
Vault executes plugin binaries when they are configured and roles are established
around them. The binary cannot be modified or replaced while running, so
upgrades cannot be performed by simply swapping the binary and updating the hash
in the plugin catalog.
~> Plugin versioning was introduced with Vault 1.12.0, so if your Vault server is
on 1.11.x or earlier, see the [1.11.x version of this page](/docs/v1.11.x/upgrading/plugins)
for plugin upgrade instructions.
Instead, you can restart or reload a plugin with the
`sys/plugins/reload/backend` [API][plugin_reload_api]. Follow these steps to
replace or upgrade a Vault plugin binary:
### Upgrading auth and secrets plugins
1. [Register][plugin_registration] version 1 of `my-db-plugin` to the catalog.
Skip this step if your plugin is already registered.
The process is nearly identical for auth and secret plugins. If you are upgrading
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
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
database \ # type
my-db-plugin
$ vault plugin register
-sha256=<SHA256 Hex value of the plugin binary> \
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.
```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
name, but with updated command to run version 2 of `my-db-plugin` and updated
sha256 of the new binary
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> \
database \ # type
my-db-plugin
$ vault plugin register \
-sha256=<SHA256 Hex value of the plugin binary> \
-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
with either the `plugin` or `mounts` parameter respectively.
with either the `plugin` or `mounts` flag respectively.
```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
the reload is triggered, Vault will kill `my-db-plugin`’s process and start the
new plugin process for `my-db-plugin` version 2.
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-secret-plugin`’s process and start the
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
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
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
design is not obvious since many of them are built into Vault.
```shell-session
$ 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
Secrets engines:
1. [Mount][plugin_management] the plugin. Skip this step if your initial plugin
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
$ vault plugin list secret
Plugins
-------
ad
alicloud
aws
azure
cassandra
consul
gcp
gcpkms
kv
ldap
mongodb
mongodbatlas
mssql
mysql
nomad
openldap
pki
postgresql
rabbitmq
ssh
terraform
totp
transit
Name Version
---- -------
ad v0.14.0+builtin
alicloud v0.13.0+builtin
aws v1.12.0+builtin.vault
azure v0.14.0+builtin
cassandra v1.12.0+builtin.vault
consul v1.12.0+builtin.vault
gcp v0.14.0+builtin
gcpkms v0.13.0+builtin
kv v0.13.3+builtin
ldap v1.12.0+builtin.vault
mongodb v1.12.0+builtin.vault
mongodbatlas v0.8.0+builtin
mssql v1.12.0+builtin.vault
mysql v1.12.0+builtin.vault
nomad v1.12.0+builtin.vault
openldap v0.9.0+builtin
pki v1.12.0+builtin.vault
postgresql v1.12.0+builtin.vault
rabbitmq v1.12.0+builtin.vault
ssh v1.12.0+builtin.vault
terraform v0.6.0+builtin
totp v1.12.0+builtin.vault
transit v1.12.0+builtin.vault
```
This will list all Secrets engines, internal (built-in) or external. To find
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
### Additional Upgrade Notes
* 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
different Azure Secrets mounts, they'll all change after the replacement. If
you don't want that, you'll need to register the plugin under a different name
and start with a fresh mount.
* In most cases, data upgrade and downgrade is not an issue. If the "new" version
introduces new data and you downgrade, the "old" version will ignore the
extraneous data. In some cases upgrading changes existing data in non-backwards
compatible ways, so it is good to check whether this is an issue.
* Overwriting an existing version in the catalog will affect all uses of that
plugin version. So if you have 5 different Azure Secrets mounts using v1.0.0,
they'll all start using the new binary if you overwrite it. We recommend
treating plugin versions in the catalog as immutable, much like version control
tags.
* Each plugin has its own data within Vault storage. While it is rare for HashiCorp
maintained plugins to update their storage schema, it is up to plugin authors
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_registration]: /docs/plugins/plugin-architecture#plugin-registration