`vault_plugin`¶

Manage Vault (or OpenBao) plugins.

Added in version 1.8.0.

Important

This module requires the general Vault setup.

saltext.vault.modules.vault_plugin.list_(plugin_type)[source]¶

List all registered plugins of a specific type.

CLI Example:

salt '*' vault_plugin.list auth

Required policy:

path "sys/plugins/catalog" {
    capabilities = ["read"]
}

plugin_type: Plugin type to list. Either auth, database or secret.

saltext.vault.modules.vault_plugin.list_versions(plugin_type, name)[source]¶

List all registered versions of a plugin.

CLI Example:

salt '*' vault_plugin.list_versions database mymysql-database-plugin

Required policy:

path "sys/plugins/catalog" {
    capabilities = ["read"]
}

plugin_type: Type of the plugin to list versions of. Either auth, database or secret.
name: Name of the plugin to list versions of.

saltext.vault.modules.vault_plugin.list_detailed(plugin_type=None, name=None, builtin=None, version=None, sha256=None)[source]¶

List detailed information about plugins.

CLI Example:

salt '*' vault_plugin.list_detailed
salt '*' vault_plugin.list_detailed database
salt '*' vault_plugin.list_detailed database mymysql-database-plugin

Required policy:

path "sys/plugins/catalog" {
    capabilities = ["read"]
}

plugin_type: Filter for type of plugin. Optional. Either auth, database or secret.
name: Filter for the name of the plugin. Optional. Can be a glob.
builtin: Filter for plugins that are builtin/not builtin. Either true or false. Optional.
version: Filter for the plugin version. Optional. Can be a glob. Set this to the empty string to filter for unversioned plugins.
sha256: Filter for plugins that match this SHA256 hash. Optional.

saltext.vault.modules.vault_plugin.list_pins(plugin_type=None, name=None)[source]¶

List detailed information about pinned plugins.

CLI Example:

salt '*' vault_plugin.list_pins
salt '*' vault_plugin.list_pins database
salt '*' vault_plugin.list_pins name='my*'

Required policy:

path "sys/plugins/pins" {
    capabilities = ["read"]
}

plugin_type: Filter for type of plugin. Optional. Either auth, database or secret.
name: Filter for the name of the plugin. Optional. Can be a glob.

saltext.vault.modules.vault_plugin.pinned_version(plugin_type, name)[source]¶

Get the pinned version of a plugin, if any.

CLI Example:

salt '*' vault_plugin.pinned_version database mymysql-database-plugin

Required policy:

path "sys/plugins/pins/<plugin_type>/<name>" {
    capabilities = ["read"]
}

plugin_type: Type of the plugin to show pinned version for. Either auth, database or secret.
name: Name of the plugin to show pinned version for.

saltext.vault.modules.vault_plugin.pin(plugin_type, name, version, now=False, now_globally=False)[source]¶

Pin a plugin to a specific version. Optionally reload existing mounts to apply new pin.

Note

Only available on Vault.

CLI Example:

salt '*' vault_plugin.pin database mymysql-database-plugin v1.2.3
salt '*' vault_plugin.pin database mymysql-database-plugin v1.2.3 now=true
salt '*' vault_plugin.pin database mymysql-database-plugin v1.2.3 now=true now_globally=true

Required policy:

path "sys/plugins/pins/<plugin_type>/<name>" {
    capabilities = ["update"]
}

# For reload behavior
path "sys/plugins/reload/<plugin_type>/<name>" {
    capabilities = ["update"]
}

plugin_type: Type of the plugin to pin. Either auth, database or secret.
name: Name of the plugin to pin.
now: After pinning, reload all mounts of the plugin. Defaults to false.
now_globally: When now is true, begin reloading plugin on all cluster nodes. Defaults to false, which only reloads mounts on the targeted node.

saltext.vault.modules.vault_plugin.unpin(plugin_type, name, now=False, now_globally=False)[source]¶

Unpin a plugin. Optionally reload existing mounts to apply removed restriction.

Note

Only available on Vault.

CLI Example:

salt '*' vault_plugin.unpin database mymysql-database-plugin
salt '*' vault_plugin.unpin database mymysql-database-plugin now=true
salt '*' vault_plugin.unpin database mymysql-database-plugin now=true now_globally=true

Required policy:

path "sys/plugins/pins/<plugin_type>/<name>" {
    capabilities = ["delete"]
}

# For reload behavior
path "sys/plugins/reload/<plugin_type>/<name>" {
    capabilities = ["update"]
}

plugin_type: Type of the plugin to pin. Either auth, database or secret.
name: Name of the plugin to pin.
now: After unpinning, reload all mounts of the plugin. Defaults to false.
now_globally: When now is true, begin reloading plugin on all cluster nodes. Defaults to false, which only reloads mounts on the targeted node.

saltext.vault.modules.vault_plugin.get_config(plugin_type, name, version=None)[source]¶

Get plugin configuration of a specific plugin (version).

CLI Example:

salt '*' vault_plugin.get_config database mysql-database-plugin
salt '*' vault_plugin.get_config database mymysql-database-plugin version=v1.0.0

Required policy:

path "sys/plugins/catalog/<plugin_type>/<name>" {
    capabilities = ["read", "sudo"]
}

plugin_type

Type of the plugin to get config for. Either auth, database or secret.

name

Name of the plugin to get config for.

version

Registered plugin version to get configuration for.

Behavior if unspecified:

If the plugin is a builtin plugin or an unversioned custom one, this works in a straightforward way.
If the plugin is a versioned custom one, Vault errors. In this case, this function tries to find the version Vault defaults to for new mounts. First, by checking if any version is pinned (on Vault). If not, looks for the highest version and returns its configuration.

Explicitly set this to the empty string to disable fallback behavior and query for builtin/unversioned plugins only.

saltext.vault.modules.vault_plugin.register(plugin_type, name, sha256=None, command=None, args=None, env=None, version=None, oci_image=None, runtime=None, download=False)[source]¶

CLI Example:

salt '*' vault_plugin.register database mymysql-database-plugin deadbeefcafebabe...

Required policy:

path "sys/plugins/catalog/<plugin_type>/<name>" {
    capabilities = ["create", "update", "sudo"]
}

plugin_type: Type of the plugin to register. Either auth, database or secret.
name: Name of the plugin to register.
sha256: SHA256 hexdigest of the plugin binary or the OCI image. Before Vault runs a plugin, it checks the plugin SHA against this value. If the actual SHA of the plugin binary and the SHA provided here do not match, Vault refuses to run the plugin.

Note

Required to register a plugin binary. Must be unset to register an extracted .zip file.
command: Specifies the command used to execute the plugin. This is relative to the plugin directory, e.g. “myplugin”, or if oci_image is also specified, it is relative to the image’s working directory. If unspecified and oci_image is not defined, defaults to the name.

Note

Ignored when registering with an extracted .zip file as the associated run command is known then.
args: List of arguments used to execute the plugin. Optional.
env: List of environment variables used during the execution of the plugin. Each entry is of the form “key=value”.
version: Specifies the semantic version of this plugin. Used as the tag when specifying oci_image, but with any leading ‘v’ trimmed. You can omit version to register a plugin binary, but you must provide an explicit version to register an extracted .zip file
oci_image: Vault only: Specifies OCI image to run. If specified, setting command, args, and env updates the container’s entrypoint, args, and environment variables (append-only) respectively.
runtime: Vault only: Specifies Vault plugin runtime to use if oci_image is specified.
download: Vault Enterprise only: Download the specified plugin from HashiCorp’s releases page.

saltext.vault.modules.vault_plugin.deregister(plugin_type, name, version=None)[source]¶

Deregister a plugin.

CLI Example:

salt '*' vault_plugin.deregister database mymysql-database-plugin

Required policy:

path "sys/plugins/catalog/<plugin_type>/<name>" {
    capabilities = ["delete", "sudo"]
}

plugin_type: Type of the plugin to deregister. Either auth, database or secret.
name: Name of the plugin to deregister.
version: Specifies the semantic version of the plugin to delete.

saltext.vault.modules.vault_plugin.reload(plugin_type, name, globally=False)[source]¶

Reload a plugin across all namespaces. Kills all instances and starts new ones, respecting a potentially modified pin.

Note

Only available on Vault.

Note

Must be run inside the root namespace.

CLI Example:

salt '*' vault_plugin.reload database mymysql-database-plugin

Required policy:

path "sys/plugins/reload/<plugin_type>/<name>" {
    capabilities = ["update"]
}

plugin_type: Type of the plugin to reload. Either auth, database or secret.
name: Name of the plugin to reload.
globally: By default, reloads the plugin on the targeted Vault instance. If true, begins reloading the plugin on all instances of a cluster.

saltext.vault.modules.vault_plugin.reload_named(name, globally=False)[source]¶

Reload plugin by name in the current namespace.

CLI Example:

salt '*' vault_plugin.reload_name mysql-database-plugin

Required policy:

path "sys/plugins/reload/backend" {
    capabilities = ["update"]
}

name: Name of the plugin to reload.
globally: By default, reloads the plugin on the targeted Vault instance. If true, begins reloading the plugin on all instances of a cluster.

saltext.vault.modules.vault_plugin.reload_mounts(mounts, globally=False)[source]¶

Reload plugins for specified mounts in the current namespace.

CLI Example:

salt '*' vault_plugin.reload_mounts database
salt '*' vault_plugin.reload_mounts mounts='[database, other_mount]'

Required policy:

path "sys/plugins/reload/backend" {
    capabilities = ["update"]
}

mounts: Mount names or list thereof to reload backing plugins for.
globally: By default, reloads the mounts on the targeted Vault instance. If true, begins reloading the mounts on all instances of a cluster.

vault_plugin¶

`vault_plugin`¶