`vault_db`¶

Manage the Vault database secret engine, request and cache leased database credentials.

Added in version 1.1.0.

Important

This module requires the general Vault setup.

saltext.vault.modules.vault_db.list_connections(mount='database')[source]¶

List configured database connections.

CLI Example:

salt '*' vault_db.list_connections

mount: The mount path the DB backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.fetch_connection(name, mount='database')[source]¶

Read a configured database connection. Returns None if it does not exist.

API method docs.

CLI Example:

salt '*' vault_db.fetch_connection mydb

name: The name of the database connection.
mount: The mount path the database backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.write_connection(name, plugin, version='', verify=True, allowed_roles=None, root_rotation_statements=None, password_policy=None, rotate=True, mount='database', **kwargs)[source]¶

Create/update a configured database connection.

Note

This endpoint distinguishes between create and update ACL capabilities.

Note

It is highly recommended to use a Vault-specific user rather than the admin user in the database when configuring the plugin. This user will be used to create/update/delete users within the database so it will need to have the appropriate permissions to do so. If the plugin supports rotating the root credentials, it is highly recommended to perform that action after configuring the plugin. This will change the password of the user configured in this step. The new password will not be viewable by users.

API method docs.

CLI Example:

salt '*' vault_db.write_connection mydb elasticsearch                 url=http://127.0.0.1:9200 username=vault password=hunter2

name: The name of the database connection.
plugin: The name of the database plugin. Known plugins to this module are: cassandra, couchbase, elasticsearch, influxdb, hanadb, mongodb, mongodb_atlas, mssql, mysql, oracle, postgresql, redis, redis_elasticache, redshift, snowflake. If you pass an unknown plugin, make sure its Vault-internal name can be formatted as {plugin}-database-plugin and to pass all required parameters as kwargs.
version: Specifies the semantic version of the plugin to use for this connection.
verify: Verify the connection during initial configuration. Defaults to True.
allowed_roles: List of the roles allowed to use this connection. ["*"] means any role can use this connection. Defaults to empty (no role can use it).
root_rotation_statements: Specifies the database statements to be executed to rotate the root user’s credentials. See the plugin’s API page for more information on support and formatting for this parameter.
password_policy: The name of the password policy to use when generating passwords for this database. If not specified, this will use a default policy defined as: 20 characters with at least 1 uppercase, 1 lowercase, 1 number, and 1 dash character.
rotate: Rotate the root credentials after plugin setup. Defaults to True.
mount: The mount path the database backend is mounted to. Defaults to database.
kwargs: Different plugins require different parameters. You need to make sure that you pass them as supplemental keyword arguments. For known plugins, the required arguments will be checked.

saltext.vault.modules.vault_db.delete_connection(name, mount='database')[source]¶

Delete a configured database connection. Returns None if it does not exist.

API method docs.

CLI Example:

salt '*' vault_db.delete_connection mydb

name: The name of the database connection.
mount: The mount path the database backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.reset_connection(name, mount='database')[source]¶

Close a connection and restart its plugin with the configuration stored in the barrier.

API method docs.

CLI Example:

salt '*' vault_db.reset_connection mydb

name: The name of the database connection.
mount: The mount path the database backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.rotate_root(name, mount='database')[source]¶

Rotate the “root” user credentials stored for the database connection.

Warning

The rotated password will not be accessible, so it is highly recommended to create a dedicated user account as Vault’s configured “root”.

API method docs.

CLI Example:

salt '*' vault_db.rotate_root mydb

name: The name of the database connection.
mount: The mount path the database backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.list_roles(static=False, mount='database')[source]¶

List configured database roles.

API method docs. API method docs static.

CLI Example:

salt '*' vault_db.list_roles

static: Whether to list static roles. Defaults to False.
mount: The mount path the DB backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.fetch_role(name, static=False, mount='database')[source]¶

Read a configured database role. Returns None if it does not exist.

API method docs. API method docs static.

CLI Example:

salt '*' vault_db.fetch_role myrole

name: The name of the database role.
static: Whether this role is static. Defaults to False.
mount: The mount path the database backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.write_static_role(name, connection, username, rotation_period, rotation_statements=None, credential_type=None, credential_config=None, mount='database')[source]¶

Create/update a database Static Role. Mind that not all databases support Static Roles.

API method docs.

CLI Example:

salt '*' vault_db.write_static_role myrole mydb myuser 24h

name: The name of the database role.
connection: The name of the database connection this role applies to.
username: The username to manage.
rotation_period: Specifies the amount of time Vault should wait before rotating the password. The minimum is 5s.
rotation_statements: Specifies the database statements to be executed to rotate the password for the configured database user. Not every plugin type will support this functionality.
credential_type: Specifies the type of credential that will be generated for the role. Options include: password, rsa_private_key. Defaults to password. See the plugin’s API page for credential types supported by individual databases.
credential_config: Specifies the configuration for the given credential_type as a mapping. For password, only password_policy can be passed. For rsa_private_key, key_bits (defaults to 2048) and format (defaults to pkcs8) are available.
mount: The mount path the database backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.write_role(name, connection, creation_statements, default_ttl=None, max_ttl=None, revocation_statements=None, rollback_statements=None, renew_statements=None, credential_type=None, credential_config=None, mount='database')[source]¶

Create/update a regular database role.

API method docs.

CLI Example:

salt '*' vault_db.write_role myrole mydb \
    \["CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'", "GRANT SELECT ON *.* TO '{{name}}'@'%'"\]

name: The name of the database role.
connection: The name of the database connection this role applies to.
creation_statements: Specifies a list of database statements executed to create and configure a user, usually templated with {{name}} and {{password}}. Required.
default_ttl: Specifies the TTL for the leases associated with this role. Accepts time suffixed strings (1h) or an integer number of seconds. Defaults to system/engine default TTL time.
max_ttl: Specifies the maximum TTL for the leases associated with this role. Accepts time suffixed strings (1h) or an integer number of seconds. Defaults to sys/mounts’s default TTL time; this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL), but it is not allowed to be longer.
revocation_statements: Specifies a list of database statements to be executed to revoke a user.
rollback_statements: Specifies a list of database statements to be executed to rollback a create operation in the event of an error. Availability and formatting depend on the specific plugin.
renew_statements: Specifies a list of database statements to be executed to renew a user. Availability and formatting depend on the specific plugin.
credential_type: Specifies the type of credential that will be generated for the role. Options include: password, rsa_private_key. Defaults to password. See the plugin’s API page for credential types supported by individual databases.
credential_config: Specifies the configuration for the given credential_type as a mapping. For password, only password_policy can be passed. For rsa_private_key, key_bits (defaults to 2048) and format (defaults to pkcs8) are available.
mount: The mount path the database backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.delete_role(name, static=False, mount='database')[source]¶

Delete a configured database role.

API method docs. API method docs static.

CLI Example:

salt '*' vault_db.delete_role myrole

name: The name of the database role.
static: Whether this role is static. Defaults to False.
mount: The mount path the database backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.get_creds(name, static=False, cache=True, valid_for=salt.defaults.NOT_SET, check_server=False, renew_increment=salt.defaults.NOT_SET, revoke_delay=salt.defaults.NOT_SET, meta=salt.defaults.NOT_SET, mount='database', _warn_about_attr_change=True)[source]¶

Read credentials based on the named role.

API method docs. API method docs static.

CLI Example:

salt '*' vault_db.get_creds myrole

name

The name of the database role.

static

Whether this role is static. Defaults to False.

cache

Whether to use cached credentials local to this minion to avoid unnecessary reissuance. When static is false, set this to a string to be able to use multiple distinct credentials using the same role on the same minion. Set this to false to disable caching. Defaults to true.

Note

This uses the same cache backend as the Vault integration, so make sure you configure a persistent backend like disk if you expect the credentials to survive a single run.

Hint

For some applications, you might need to know the resulting cache key of the credential lease. The cache key is composed as a concatenation of the following parts (with .):

db
<mount>
dynamic if static=False, else static
<name> (the name of the database role)
default if cache=True or static=True, otherwise the value of cache

Examples for a role named foo:

mount=database, static=False, cache=True: db.database.dynamic.foo.default
mount=mariadb, static=False, cache=alt: db.mariadb.dynamic.foo.alt
mount=mariadb, static=True, cache=True: db.mariadb.static.foo.default

valid_for

When using cache, ensure the credentials are valid for at least this amount of time, otherwise request new ones. This can be an integer, which will be interpreted as seconds, or a time string using the same format as Vault does: Suffix s for seconds, m for minuts, h for hours, d for days. This will be cached together with the lease and might be used by other modules later.

check_server

Check on the Vault server whether the lease is still active and was not revoked early. Defaults to false.

renew_increment

When using cache and valid_for results in a renewal attempt, request this amount of time extension on the lease. This will be cached together with the lease and might be used by other modules later.

revoke_delay

When using cache and valid_for results in a revocation, set the lease validity to this value to allow a short amount of delay between the issuance of the new lease and the revocation of the old one. Defaults to 60. This will be cached together with the lease and might be used by other modules later.

meta

When using cache, this value will be cached together with the lease. It will be emitted by the vault_lease beacon module whenever a lease is running out (usually because it cannot be extended further). It is intended to support the reactor in deciding what needs to be done in order to to reconfigure dependent, Vault-unaware software with newly issued credentials. Entirely optional.

mount

The mount path the database backend is mounted to. Defaults to database.

saltext.vault.modules.vault_db.clear_cached(name=None, mount=None, cache=None, static=None, delta=None, flush_on_failure=True)[source]¶

Clear and revoke cached database credentials matching specified parameters.

CLI Example:

salt '*' vault_db.clear_cached name=myrole mount=database
salt '*' vault_db.clear_cached mount=database
salt '*' vault_db.clear_cached

name: Only clear credentials using this role name.
mount: Only clear credentials from this mount.
cache: Only clear credentials using this cache name (refer to get_creds for details).
static: Only clear static (True) or dynamic (False) credentials.
delta: Time after which the leases should be revoked by Vault. Defaults to what was set on the lease(s) during creation or 60s.
flush_on_failure: If a revocation fails, remove the lease from cache anyways. Defaults to true.

saltext.vault.modules.vault_db.list_cached(name=None, mount=None, cache=None, static=None)[source]¶

List cached database credentials matching specified parameters.

CLI Example:

salt '*' vault_db.list_cached name=myrole mount=database
salt '*' vault_db.list_cached mount=database
salt '*' vault_db.list_cached

name: Only list credentials using this role name.
mount: Only list credentials from this mount.
cache: Only list credentials using this cache name (refer to get_creds for details).
static: Only list static (True) or dynamic (False) credentials.

saltext.vault.modules.vault_db.renew_cached(name=None, mount=None, cache=None, static=None, increment=None)[source]¶

Renew cached database credentials matching specified parameters.

CLI Example:

salt '*' vault_db.renew_cached name=myrole mount=database
salt '*' vault_db.renew_cached mount=database
salt '*' vault_db.renew_cached

name: Only renew credentials using this role name.
mount: Only renew credentials from this mount.
cache: Only renew credentials using this cache name (refer to get_creds for details).
static: Only renew static (True) or dynamic (False) credentials.
increment: Request the leases to be valid for this amount of time from the current point of time onwards. Can also be used to reduce the validity period. The server might not honor this increment. Can be an integer (seconds) or a time string like 1h. Optional. If unset, defaults to what was set on the lease during creation or the lease’s default TTL.

saltext.vault.modules.vault_db.rotate_static_role(name, mount='database')[source]¶

Rotate Static Role credentials stored for a given role name.

API method docs static.

CLI Example:

salt '*' vault_db.rotate_static_role mystaticrole

name: The name of the database role.
mount: The mount path the database backend is mounted to. Defaults to database.

vault_db¶

`vault_db`¶