plugin
The plugin
command groups subcommands for interacting with Vault's plugins and the plugin catalog
Examples
List all available secret plugins in the catalog:
$ vault plugin list secret
Name Version
---- -------
ad v0.14.0+builtin
alicloud v0.13.0+builtin
...
Register a new secret plugin to the catalog:
$ vault plugin register \
-sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
secret my-custom-plugin
Success! Registered plugin: my-custom-plugin
Get information about a plugin in the catalog:
$ vault plugin info secret my-custom-plugin
Key Value
--- -----
args []
builtin false
command my-custom-plugin
deprecation_status n/a
name my-custom-plugin
oci_image n/a
runtime n/a
sha256 33e72f3d30ff2acdbf3cf3c8fa1c8945b60dab876c4226ab25617a63c9f16cc5
version n/a
Usage
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
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 of the subcommand in the sidebar.
plugin deregister
The plugin deregister
command deregisters an existing plugin from Vault's plugin catalog. If the plugin does not exist, no error is returned. The plugin's type of "auth", "database", or "secret" must be included.
Examples
Deregister a plugin:
$ vault plugin deregister auth my-custom-plugin
Success! Deregistered plugin (if it was registered): my-custom-plugin
Usage
The following flags are available in addition to the standard set of flags included on all commands.
-version
(string: "")
- Semantic version of the plugin to deregister. If unset, only an unversioned plugin may be deregistered.
plugin info
The plugin info
displays information about a plugin in the catalog. The plugin's type of "auth", "database", or "secret" must be included.
deprecation_status field
As of 1.12, all builtin plugins will have an associated Deprecation Status. This status will be reflected in the deprecation_status
key/value pair, seen below.
Examples
Display information about a plugin
$ vault plugin info -version=v1.0.0 auth my-custom-plugin
Key Value
--- -----
args []
builtin false
command my-custom-plugin
deprecation_status n/a
name my-custom-plugin
oci_image n/a
runtime n/a
sha256 04ce575260fa3a2cfc477d13ac327108c50838a03917ec4d6df38ecdc64452d1
version v1.0.0
$ vault plugin info database postgresql-database-plugin
Key Value
--- -----
args []
builtin true
command n/a
deprecation_status supported
name postgresql-database-plugin
oci_image n/a
runtime n/a
sha256 n/a
version n/a
Usage
The following flags are available in addition to the standard set of flags included on all commands.
Output options
-field
(string: "")
- Print only the field with the given name. Specifying this option will take precedence over other formatting directives. The result will not have a trailing newline making it ideal for piping to other processes.-format
(string: "table")
- Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via theVAULT_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.
plugin list
The plugin list
command lists all available plugins in the plugin catalog. It can be used alone or with a type such as "auth", "database", or "secret".
Deprecation status column
As of 1.12, all builtin plugins will have an associated Deprecation Status. This status will be reflected in the Deprecation Status
column, seen below. All non-builtin plugins will show a Deprecation Status
of "n/a".
Examples
List all available plugins in the catalog.
$ vault plugin list
Name Type Version
---- ---- -------
alicloud auth v0.13.0+builtin
# ...
$ vault plugin list database
Name Version
---- -------
cassandra-database-plugin v1.13.0+builtin.vault
# ...
List detailed plugin information:
$ vault plugin list -detailed
Name Type Version Container Deprecation Status
---- ---- ------- --------- ------------------
alicloud auth v0.12.0+builtin false supported
app-id auth v1.12.0+builtin.vault false pending removal
# ...
Usage
The following flags are available in addition to the standard set of flags included on all commands.
Output options
-format
(string: "table")
- Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via theVAULT_FORMAT
environment variable.
Command options
-detailed
(bool: false)
- Print detailed information such as version and deprecation status about each plugin.
plugin register
The plugin register
command registers a new plugin in Vault's plugin catalog. The plugin's type of "auth", "database", or "secret" must be included.
Examples
Register a plugin:
$ vault plugin register \
-sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
auth my-custom-plugin
Success! Registered plugin: my-custom-plugin
Register a plugin with custom args:
$ vault plugin register \
-sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
-args=--with-glibc,--with-curl-bindings \
auth my-custom-plugin
Usage
The following flags are available in addition to the standard set of flags included on all commands.
Output options
-format
(string: "table")
- Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via theVAULT_FORMAT
environment variable.
Command options
-sha256
(string: <required>)
- SHA256 of the plugin binary or the OCI image provided. This is required for all plugins.-args
([]string: [])
- Argument to pass to the plugin when starting. This flag can be specified multiple times to specify multiple args.-command
(string: "")
- Command to spawn the plugin. This defaults to the name of the plugin if both-oci_image
and-command
are unspecified.-env
([]string: [])
- Environment variables to set for the plugin when starting. This flag can be specified multiple times to specify multiple environment variables.-oci_image
(string: "")
- OCI image to run. If specified, setting-command
,-args
, and-env
will update the container's entrypoint, args, and environment variables (append-only) respectively.-runtime
(string: "")
- Vault plugin runtime to use if-oci_image
is specified.-version
(string: "")
- Semantic version of the plugin. Used as the tag when specifying-oci_image
, but any leading 'v' will automatically be trimmed.
plugin reload
The plugin reload
command is used to reload mounted plugin backends. Either the plugin name (plugin
) or the desired plugin backend mounts (mounts
) must be provided, but not both. In the case that the plugin name is provided, all mounted paths that use that plugin backend will be reloaded.
Examples
Reload a plugin by name:
$ vault plugin reload -plugin my-custom-plugin
Success! Reloaded plugin: my-custom-plugin
Reload an auth plugin by mount:
$ vault plugin reload \
-mounts auth/my-custom-plugin-1 \
-mounts auth/my-custom-plugin-2
Success! Reloaded mounts: [auth/my-custom-plugin-1/ auth/my-custom-plugin-2/]
Reload a secrets plugin by mount:
$ vault plugin reload \
-mounts my-custom-plugin-1 \
-mounts my-custom-plugin-2
Success! Reloaded mounts: [my-custom-plugin-1/ my-custom-plugin-2/]
Usage
The following flags are available in addition to the standard set of flags included on all commands.
Command options
-plugin
(string: "")
- The name of the plugin to reload, as registered in the plugin catalog.-mounts
(array: [])
- Array or comma-separated string mount paths of the plugin backends to reload.-scope
(string: "")
- The scope of the reload. For local reloads, omit this flag. For reloads that span multiple Vault clusters, useglobal
.
plugin runtime
The plugin runtime
command groups subcommands for interacting with and configuring the context within which your external plugins run.
Limited type support
Support for runtime types is currently limited to `container`.
Limited OS support
Support for the 'container` runtime is currently limited to Linux.
If you register a container plugin without referencing a plugin runtime, it will use gVisor's OCI runtime runsc
by default, with no resource limits. You can use plugin runtimes to configure other OCI-compliant runtimes such as runc
. Vault does not come packaged with any supporting container runtimes, and you must separately install whichever you want to use.
To use a registered plugin runtime, use the -runtime
option with the plugin registration command.
See containerized plugins for more details on running external plugins in containers.
Examples
Register a new plugin runtime to the catalog:
$ vault plugin runtime register -type=container -oci_runtime=runc runc
Success! Registered plugin runtime: runc
List all available plugin runtimes in the catalog:
$ vault plugin runtime list
Name Type OCI Runtime Parent Cgroup CPU Nanos Memory Bytes
---- ---- ----------- ------------- --------- ------------
runc container runc n/a 0 0
Get information about a plugin runtime in the catalog:
$ vault plugin runtime info -type=container runc
Key Value
--- -----
cgroup_parent n/a
cpu_nanos 0
memory_bytes 0
name runc
oci_runtime runc
type container
Usage
Usage: vault plugin runtime <subcommand> [options] [args]
# ...
Subcommands:
deregister Deregister an existing plugin runtime in the catalog
info Read information about a plugin runtime in the catalog
list Lists available plugin runtimes
register Registers a new plugin runtime in the catalog
For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar.
plugin runtime deregister
Deregister an existing plugin runtime in the catalog with the given name. Returns an error if a registered plugin references the named plugin runtime or the named runtime does not exist.
Limited type support
Support for runtime types is currently limited to `container`.
Examples
Deregister a plugin:
$ vault plugin runtime deregister -type=container my-plugin-runtime
Success! Deregistered plugin runtime: my-plugin-runtime
Usage
The following flags are available in addition to the standard set of flags included on all commands.
-type
(string: <required>)
- Plugin runtime type. Vault currently only supportscontainer
runtime type.
plugin runtime info
Displays information about a plugin runtime in the catalog with the given name. If the plugin runtime does not exist, an error is returned.
Limited type support
Support for runtime types is currently limited to `container`.
Examples
Display information about a plugin
$ vault plugin runtime info -type=container runc
Key Value
--- -----
cgroup_parent n/a
cpu_nanos 0
memory_bytes 0
name runc
oci_runtime runc
type container
Usage
The following flags are available in addition to the standard set of flags included on all commands.
Output options
-field
(string: "")
- Print information for the named field without a trailing newline. The-field
parameter takes precedence over other formatting directives.-format
(string: "table")
- Print the output for the current command in the given format. Valid formats aretable
,json
, oryaml
. Use theVAULT_FORMAT
environment variable to set your output preferences globally.
Command options
-type
(string: "")
- Plugin runtime type. Vault currently only supportscontainer
runtime type.
plugin list
List all plugin runtimes currently registered with Vault. Returns all the available plugin runtimes or an error if the set of registered runtimes is empty. Vault considers any registered plugin runtime "available", regardless of whether it is currently in use.
Examples
List all available plugin runtimes in the catalog.
$ vault plugin runtime list
Name Type OCI Runtime Parent Cgroup CPU Nanos Memory Bytes
---- ---- ----------- ------------- --------- ------------
runc container runc n/a 0 0
Usage
The following flags are available in addition to the standard set of flags included on all commands.
Output options
-format
(string: "table")
- Print the output for the current command in the given format. Valid formats aretable
,json
, oryaml
. Use theVAULT_FORMAT
environment variable to set your output preferences globally.
Command options
-type
(string: "")
- Plugin runtime type. Vault currently only supportscontainer
runtime type.
plugin runtime register
Register a new plugin runtime in the plugin runtime catalog of your Vault instance.
Limited type support
Support for runtime types is currently limited to `container`.
To use a registered plugin runtime, use the -runtime
option with the plugin registration command.
Examples
Register a plugin runtime:
$ vault plugin runtime register -type=container -oci_runtime=runc runc
Success! Registered plugin runtime: runc
Register a plugin runtime with resource limits:
vault plugin runtime register \
-type=container \
-cpu_nanos=100000000 \
runsc
Usage
The following flags are available in addition to the standard set of flags included on all commands.
Command options
-type
(string: <required>)
- Plugin runtime type. Vault currently only supportscontainer
as a runtime type.-cgroup_parent
(string: "")
- Parent cgroup to set for each container. Usecgroup_parent
to control the total resource usage for a group of plugins.-cpu_nanos
(int: 0)
- CPU limit to set per container in billionths of a CPU core. Defaults to no limit.-memory_bytes
(int: 0)
- Memory limit to set per container in bytes. Defaults to no limit.-oci_runtime
(string: "")
- Open Container Initiative (OCI) compliant container runtime to use. Default is the gVisor OCI runtime,runsc
.
Last updated