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

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.

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

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.states.vault_db.connection_absent(name, mount='database')

Ensure a database connection is absent.

name

The name of the connection.

mount

The 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

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.states.vault_db.role_absent(name, static=False, mount='database')

Ensure a database role is absent.

name

The name of the 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.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

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

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

The 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

The 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

The interval to run the beacon in. Defaults to 60.

min_ttl

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