vault_db

Manage the Vault (or OpenBao) 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.states.vault_db.connection_present(name, plugin, version=None, verify=True, allowed_roles=None, root_rotation_statements=None, password_policy=None, rotate=True, force=False, mount='database', **kwargs)

Ensure a database connection is present as specified.

name

Name of the database connection.

plugin

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

Name of the password policy to use when generating passwords for this database. If not specified, this uses 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.

force

When the plugin changes, this state fails to protect from accidental errors. Set force to True to delete existing connections with the same name and a different plugin type. Defaults to False.

mount

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

saltext.vault.states.vault_db.connection_absent(name, mount='database')

Ensure a database connection is absent.

name

Name of the connection.

mount

Mount path the database backend is mounted to. Defaults to database.

saltext.vault.states.vault_db.role_present(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')

Ensure a regular database role is present as specified.

name

Name of the database role.

connection

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

Mount path the database backend is mounted to. Defaults to database.

saltext.vault.states.vault_db.role_absent(name, static=False, mount='database')

Ensure a database role is absent.

name

Name of the role.

static

Whether this role is static. Defaults to False.

mount

Mount path the database backend is mounted to. Defaults to database.

saltext.vault.states.vault_db.static_role_present(name, connection, username, rotation_period, rotation_statements=None, credential_type=None, credential_config=None, mount='database')

Ensure a database Static Role is present as specified.

name

Name of the database role.

connection

Name of the database connection this role applies to.

username

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 supports this functionality.

credential_type

Specifies the type of credential that is 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

Mount path the database backend is mounted to. Defaults to database.

saltext.vault.states.vault_db.creds_cached(name, static=False, cache=None, valid_for=salt.defaults.NOT_SET, renew_increment=None, revoke_delay=None, meta=None, mount='database', **kwargs)

Ensure valid credentials are present in the minion’s cache based on the named role. Supports mod_beacon.

Note

This function is mostly intended to associate a specific credential with a beacon that warns about expiry and allows to run an associated state to reconfigure an application with new credentials. See the vault_lease beacon module for an example state to configure a lease together with a beacon.

name

Name of the database role.

static

Whether this role is static. Defaults to False.

cache

A variable cache suffix to be able to use multiple distinct credentials using the same role on the same minion. Ignored when static is 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.

valid_for

Ensure the credentials are valid for at least this amount of time, otherwise request new ones. This can be an integer, which is 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. Defaults to 0.

renew_increment

When using cache and valid_for results in a renewal attempt, request this amount of time extension on the lease. This is 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 is cached together with the lease and might be used by other modules later.

meta

When using cache, this value is 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

Mount path the database backend is mounted to. Defaults to database.

saltext.vault.states.vault_db.creds_uncached(name, static=False, cache=None, mount='database', **kwargs)

Ensure credentials are absent in the minion’s cache based on the named role. Supports mod_beacon.

Note

This function is mostly intended to remove a cached lease and its beacon. See creds_cached() for a more detailed description. To remove the associated beacon together with the lease, just pass beacon: true as a parameter to this state.

name

Name of the database role.

static

Whether this role is static. Defaults to False.

cache

A variable cache suffix to be able to use multiple distinct credentials using the same role on the same minion. Ignored when static is true.

mount

Mount path the database backend is mounted to. Defaults to database.

saltext.vault.states.vault_db.mod_beacon(name, sfun=None, static=False, cache=None, mount='database', **kwargs)

Associates a Vault lease with a vault_lease beacon and possibly a state.

beacon_interval

Interval to run the beacon in. Defaults to 60.

min_ttl

If this minimum TTL on the lease is undercut, the beacon fires an event. Defaults to 0.