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 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.

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 the VAULT_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 the VAULT_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, use global.

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 supports container 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 are table, json, or yaml. Use the VAULT_FORMAT environment variable to set your output preferences globally.

Command options

• -type (string: "") - Plugin runtime type. Vault currently only supports container 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 are table, json, or yaml. Use the VAULT_FORMAT environment variable to set your output preferences globally.

Command options

• -type (string: "") - Plugin runtime type. Vault currently only supports container 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 supports container as a runtime type.

• -cgroup_parent (string: "") - Parent cgroup to set for each container. Use cgroup_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.