# 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()

  Added 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)

  Added 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)

  Added 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)

  Added 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)

  Added 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)

  Added 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()

  Added 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()

  Added 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)

  Added 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)

  Added 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)

  Added 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)

  Added 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