salt.runners.vault

Warning

This module will be removed from Salt in version 3009 in favor of the vault Salt Extension.

Runner functions supporting the Vault modules. Configuration instructions are documented in the execution module docs.

maintainer:

SaltStack

maturity:

new

platform:

all

class salt.runners.vault.LazyPillar(opts, grains, minion_id, extra_minion_data=None)

Simulates a pillar dictionary. Only compiles the pillar once an item is requested.

salt.runners.vault.cleanup_auth()

New in version 3007.0.

Removes AppRoles and entities associated with unknown minion IDs. Can only clean up entities if the AppRole still exists.

Warning

Make absolutely sure that the configured minion approle issue mount is exclusively dedicated to the Salt master, otherwise you might lose data by using this function! (config: vault:issue:approle:mount)

This detects unknown existing AppRoles by listing all roles on the configured minion AppRole mount and deducting known minions from the returned list.

CLI Example:

salt-run vault.cleanup_auth
salt.runners.vault.clear_cache(master=True, minions=True)

New in version 3007.0.

Clears master cache of Vault-specific data. This can include: - AppRole metadata - rendered policies - cached authentication credentials for impersonated minions - cached KV metadata for impersonated minions

CLI Example:

salt-run vault.clear_cache
salt-run vault.clear_cache minions=false
salt-run vault.clear_cache master=false minions='[minion1, minion2]'
master

Clear cached data for the master context. Includes cached master authentication data and KV metadata. Defaults to true.

minions

Clear cached data for minions on the master. Can include cached authentication credentials and KV metadata for pillar compilation as well as AppRole metadata and rendered policies for credential issuance. Defaults to true. Set this to a list of minion IDs to only clear cached data pertaining to thse minions.

salt.runners.vault.generate_new_token(minion_id, signature, impersonated_by_master=False, issue_params=None)

New in version 3007.0.

Generate a Vault token for minion <minion_id>.

minion_id

The ID of the minion that requests a token.

signature

Cryptographic signature which validates that the request is indeed sent by the minion (or the master, see impersonated_by_master).

impersonated_by_master

If the master needs to create a token on behalf of the minion, this is True. This happens when the master generates minion pillars.

issue_params

Dictionary of parameters for the generated tokens. See master configuration vault:issue:token:params for possible values. Requires vault:issue:allow_minion_override_params master configuration setting to be effective.

salt.runners.vault.generate_secret_id(minion_id, signature, impersonated_by_master=False, issue_params=None)

New in version 3007.0.

Generate a Vault secret ID for minion <minion_id>. Requires the master to be configured to generate AppRoles for minions (configuration: vault:issue:type).

minion_id

The ID of the minion that requests a secret ID.

signature

Cryptographic signature which validates that the request is indeed sent by the minion (or the master, see impersonated_by_master).

impersonated_by_master

If the master needs to create a token on behalf of the minion, this is True. This happens when the master generates minion pillars.

issue_params

Dictionary of configuration values for the generated AppRole. See master configuration vault:issue:approle:params for possible values. Requires vault:issue:allow_minion_override_params master configuration setting to be effective.

salt.runners.vault.generate_token(minion_id, signature, impersonated_by_master=False, ttl=None, uses=None, upgrade_request=False)

Deprecated since version 3007.0.

Generate a Vault token for minion <minion_id>.

minion_id

The ID of the minion that requests a token.

signature

Cryptographic signature which validates that the request is indeed sent by the minion (or the master, see impersonated_by_master).

impersonated_by_master

If the master needs to create a token on behalf of the minion, this is True. This happens when the master generates minion pillars.

ttl

Ticket time to live in seconds, 1m minutes, or 2h hrs

uses

Number of times a token can be used

upgrade_request

In case the new runner endpoints have not been whitelisted for peer running, this endpoint serves as a gateway to vault.get_config. Defaults to False.

salt.runners.vault.get_config(minion_id, signature, impersonated_by_master=False, issue_params=None, config_only=False)

New in version 3007.0.

Return Vault configuration for minion <minion_id>.

minion_id

The ID of the minion that requests the configuration.

signature

Cryptographic signature which validates that the request is indeed sent by the minion (or the master, see impersonated_by_master).

impersonated_by_master

If the master needs to contact the Vault server on behalf of the minion, this is True. This happens when the master generates minion pillars.

issue_params

Parameters for credential issuance. Requires vault:issue:allow_minion_override_params master configuration setting to be effective.

config_only

In case the master is configured to issue tokens, do not include a new token in the response. This is used for configuration update checks. Defaults to false.

salt.runners.vault.get_role_id(minion_id, signature, impersonated_by_master=False, issue_params=None)

New in version 3007.0.

Return the Vault role-id for minion <minion_id>. Requires the master to be configured to generate AppRoles for minions (configuration: vault:issue:type).

minion_id

The ID of the minion that requests a role-id.

signature

Cryptographic signature which validates that the request is indeed sent by the minion (or the master, see impersonated_by_master).

impersonated_by_master

If the master needs to create a token on behalf of the minion, this is True. This happens when the master generates minion pillars.

issue_params

Dictionary of configuration values for the generated AppRole. See master configuration vault:issue:approle:params for possible values. Requires vault:issue:allow_minion_override_params master configuration setting to be effective.

salt.runners.vault.list_approles()

New in version 3007.0.

List all AppRoles that have been created by the Salt master. They are named after the minions.

CLI Example:

salt-run vault.list_approles

Required policy:

path "auth/<mount>/role" {
    capabilities = ["list"]
}
salt.runners.vault.list_entities()

New in version 3007.0.

List all entities that have been created by the Salt master. They are named salt_minion_{minion_id}.

CLI Example:

salt-run vault.list_entities

Required policy:

path "identity/entity/name" {
    capabilities = ["list"]
}
salt.runners.vault.show_approle(minion_id)

New in version 3007.0.

Show AppRole configuration for <minion_id>.

CLI Example:

salt-run vault.show_approle db1
salt.runners.vault.show_entity(minion_id)

New in version 3007.0.

Show entity metadata for <minion_id>.

CLI Example:

salt-run vault.show_entity db1
salt.runners.vault.show_policies(minion_id, refresh_pillar=<Constant.NOT_SET>, expire=None)

Show the Vault policies that are applied to tokens for the given minion.

minion_id

The ID of the minion to show policies for.

refresh_pillar

Whether to refresh the pillar data when rendering templated policies. None will only refresh when the cached data is unavailable, boolean values force one behavior always. Defaults to config value vault:policies:refresh_pillar or None.

expire

Policy computation can be heavy in case pillar data is used in templated policies and it has not been cached. Therefore, a short-lived cache specifically for rendered policies is used. This specifies the expiration timeout in seconds. Defaults to config value vault:policies:cache_time or 60.

Note

When issuing AppRoles to minions, the shown policies are read from Vault configuration for the minion's AppRole and thus refresh_pillar/expire will not be honored.

CLI Example:

salt-run vault.show_policies myminion
salt.runners.vault.sync_approles(minions=None, up=False, down=False)

New in version 3007.0.

Sync minion AppRole parameters with current settings, including associated token policies.

Note

Only updates existing AppRoles. They are issued during the first request for one by the minion. Running this will reset minion overrides, which are reapplied automatically during the next request for authentication details.

Note

Unlike when issuing tokens, AppRole-associated policies are not regularly refreshed automatically. It is advised to schedule regular runs of this function.

If no parameter is specified, will try to sync AppRoles for all known minions.

CLI Example:

salt-run vault.sync_approles
salt-run vault.sync_approles ecorp
minions

(List of) ID(s) of the minion(s) to update the AppRole for. Defaults to None.

up

Find all minions that are up and update their AppRoles. Defaults to False.

down

Find all minions that are down and update their AppRoles. Defaults to False.

salt.runners.vault.sync_entities(minions=None, up=False, down=False)

New in version 3007.0.

Sync minion entities with current settings. Only updates entities for minions with existing AppRoles.

Note

This updates associated metadata only. Entities are created only when issuing AppRoles to minions (vault:issue:type == approle).

If no parameter is specified, will try to sync entities for all known minions.

CLI Example:

salt-run vault.sync_entities
minions

(List of) ID(s) of the minion(s) to update the entity for. Defaults to None.

up

Find all minions that are up and update their associated entities. Defaults to False.

down

Find all minions that are down and update their associated entities. Defaults to False.

salt.runners.vault.unseal()

Unseal Vault server

This function uses the 'keys' from the 'vault' configuration to unseal vault server

vault:
keys:
  • n63/TbrQuL3xaIW7ZZpuXj/tIfnK1/MbVxO4vT3wYD2A

  • S9OwCvMRhErEA4NVVELYBs6w/Me6+urgUr24xGK44Uy3

  • F1j4b7JKq850NS6Kboiy5laJ0xY8dWJvB3fcwA+SraYl

  • 1cYtvjKJNDVam9c7HNqJUfINk4PYyAXIpjkpN/sIuzPv

  • 3pPK5X6vGtwLhNOFv1U2elahECz3HpRUfNXJFYLw6lid

CLI Examples:

salt-run vault.unseal