mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-11-01 19:17:58 +00:00
Docs: Plugin versioning documentation (#17460)
Co-authored-by: John-Michael Faircloth <fairclothjm@users.noreply.github.com>
This commit is contained in:
Tom Proctor
@@ -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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user