diff --git a/website/content/api-docs/secret/databases/index.mdx b/website/content/api-docs/secret/databases/index.mdx index 9650e18e1..18cf9f189 100644 --- a/website/content/api-docs/secret/databases/index.mdx +++ b/website/content/api-docs/secret/databases/index.mdx @@ -37,6 +37,9 @@ list of additional parameters. - `plugin_name` `(string: )` - 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": [] } } ``` diff --git a/website/content/api-docs/system/auth.mdx b/website/content/api-docs/system/auth.mdx index 71914dc12..ee2e6ebbe 100644 --- a/website/content/api-docs/system/auth.mdx +++ b/website/content/api-docs/system/auth.mdx @@ -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 diff --git a/website/content/api-docs/system/mounts.mdx b/website/content/api-docs/system/mounts.mdx index 789427f42..a072b936d 100644 --- a/website/content/api-docs/system/mounts.mdx +++ b/website/content/api-docs/system/mounts.mdx @@ -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: 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 diff --git a/website/content/api-docs/system/plugins-catalog.mdx b/website/content/api-docs/system/plugins-catalog.mdx index fdf72832e..835319079 100644 --- a/website/content/api-docs/system/plugins-catalog.mdx +++ b/website/content/api-docs/system/plugins-catalog.mdx @@ -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: )` – Specifies the type of this plugin. May be "auth", "database", or "secret". +- `version` `(string: "")` - Specifies the semantic version of this plugin. + - `sha256` `(string: )` – 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: )` – 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: )` – 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 ``` diff --git a/website/content/docs/commands/auth/enable.mdx b/website/content/docs/commands/auth/enable.mdx index fd0409f33..46d65b3d4 100644 --- a/website/content/docs/commands/auth/enable.mdx +++ b/website/content/docs/commands/auth/enable.mdx @@ -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. diff --git a/website/content/docs/commands/auth/list.mdx b/website/content/docs/commands/auth/list.mdx index cba7803a2..61c6a3546 100644 --- a/website/content/docs/commands/auth/list.mdx +++ b/website/content/docs/commands/auth/list.mdx @@ -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: diff --git a/website/content/docs/commands/auth/tune.mdx b/website/content/docs/commands/auth/tune.mdx index 1045e7a2c..abc401b86 100644 --- a/website/content/docs/commands/auth/tune.mdx +++ b/website/content/docs/commands/auth/tune.mdx @@ -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). diff --git a/website/content/docs/commands/plugin/index.mdx b/website/content/docs/commands/plugin/index.mdx index 1d45b0348..429f2a351 100644 --- a/website/content/docs/commands/plugin/index.mdx +++ b/website/content/docs/commands/plugin/index.mdx @@ -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 [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 diff --git a/website/content/docs/commands/plugin/info.mdx b/website/content/docs/commands/plugin/info.mdx index 485465783..783832346 100644 --- a/website/content/docs/commands/plugin/info.mdx +++ b/website/content/docs/commands/plugin/info.mdx @@ -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. diff --git a/website/content/docs/commands/plugin/register.mdx b/website/content/docs/commands/plugin/register.mdx index ae583ef90..d50b8d194 100644 --- a/website/content/docs/commands/plugin/register.mdx +++ b/website/content/docs/commands/plugin/register.mdx @@ -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. diff --git a/website/content/docs/commands/secrets/enable.mdx b/website/content/docs/commands/secrets/enable.mdx index 50a9c02f7..82963528c 100644 --- a/website/content/docs/commands/secrets/enable.mdx +++ b/website/content/docs/commands/secrets/enable.mdx @@ -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. diff --git a/website/content/docs/commands/secrets/list.mdx b/website/content/docs/commands/secrets/list.mdx index 82a3b88af..68e84f6f8 100644 --- a/website/content/docs/commands/secrets/list.mdx +++ b/website/content/docs/commands/secrets/list.mdx @@ -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 diff --git a/website/content/docs/commands/secrets/tune.mdx b/website/content/docs/commands/secrets/tune.mdx index 169258b03..ecd445c36 100644 --- a/website/content/docs/commands/secrets/tune.mdx +++ b/website/content/docs/commands/secrets/tune.mdx @@ -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). diff --git a/website/content/docs/plugins/index.mdx b/website/content/docs/plugins/index.mdx index be409fab3..c0b0ec04d 100644 --- a/website/content/docs/plugins/index.mdx +++ b/website/content/docs/plugins/index.mdx @@ -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. diff --git a/website/content/docs/upgrading/plugins.mdx b/website/content/docs/upgrading/plugins.mdx index a80c63b63..36e74a863 100644 --- a/website/content/docs/upgrading/plugins.mdx +++ b/website/content/docs/upgrading/plugins.mdx @@ -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= \ - database \ # type - my-db-plugin + $ vault plugin register + -sha256= \ + 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= \ - database \ # type - my-db-plugin + $ vault plugin register \ + -sha256= \ + -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= \ + 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= \ + -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= \ - -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