Configuration Reference

This page provides a description of all supported configuration options. All values should be placed under the vault key in the Salt configuration.

General configuration

auth

Contains authentication parameters for the local machine.

approle_mount

The name of the AppRole authentication mount point. Defaults to approle.

approle_name

The name of the AppRole. Defaults to salt-master.

Note

Only relevant when a locally configured role_id/secret_id is set to the return payload of a wrapping request, so only in very specialized use cases.

method

Currently only token and approle auth types are supported. Defaults to token.

Hint

In addition to a plain string, the required authentication credentials can also be specified as a dictionary that includes wrap_info, i.e. the return payload of a wrapping request.

role_id

The role ID of the AppRole. Required if auth:method == approle.

secret_id

The SecretID of the AppRole. Only required if the configured AppRole requires it.

token

Token to authenticate to Vault with. Required if auth:method == approle.

Hint

You can also pull configuration values, e.g. the token, from environment variables using the env SDB module:

vault:
  auth:
    method: token
    token: sdb://osenv/VAULT_TOKEN
  server:
    url: https://vault.service.domain:8200

osenv:
  driver: env

token_lifecycle

Token renewal settings.

Note

This setting can be specified inside a minion’s configuration as well and will override the master’s default for the minion.

Token lifecycle settings have significancy for any authentication method, not just token.

minimum_ttl

Specifies the time (in seconds or as a time string like 24h) an in-use token should be valid for. If the current validity period is less than this and the token is renewable, a renewal will be attempted. If it is not renewable or a renewal does not extend the ttl beyond the specified minimum, a new token will be generated.

Hint

Since leases like database credentials are tied to a token, setting this to a much higher value than the default can be necessary, depending on your specific use case and configuration.

renew_increment

Specifies the amount of time the token’s validity should be requested to be renewed for when renewing a token. When unset, will extend the token’s validity by its default ttl. Set this to false to disable token renewals.

Note

The Vault server is allowed to disregard this request.

cache

Configures token/lease and metadata cache (for KV secrets) on all hosts as well as configuration cache on minions that receive issued credentials.

backend

The cache backend in use. Defaults to session, which will store the Vault configuration in memory only for that specific Salt run. disk/file/localfs will force using the localfs driver, regardless of configured minion data cache. Setting this to anything else will use the default configured cache for minion data (cache), by default the local filesystem as well.

clear_attempt_revocation

When flushing still valid cached tokens and leases, attempt to have them revoked after a (short) delay. Defaults to 60. Set this to false to disable revocation (not recommended).

clear_on_unauthorized

When encountering an Unauthorized response with an otherwise valid token, flush the cache and request new credentials. Defaults to true.

Tip

If your policies are relatively stable, disabling this will prevent a lot of unnecessary overhead, with the tradeoff that once they change, you might have to clear the cache manually or wait for the token to expire.

config

The time in seconds to cache queried configuration from the master. Defaults to 3600 (one hour). Set this to null to disable cache expiration. Changed server configuration on the master will still be recognized, but changes in auth and cache will need a manual update using vault.update_config or cache clearance using vault.clear_cache.

Note

Expiring the configuration will also clear cached authentication credentials and leases.

expire_events

Fire an event when the session cache containing leases is cleared (vault/cache/<scope>/clear) or cached leases have expired (vault/lease/<cache_key>/expire). A reactor can be employed to ensure fresh leases are issued. Defaults to false.

kv_metadata

The time in seconds to cache KV metadata used to determine if a path is using version 1/2 for. Defaults to connection, which will clear the metadata cache once a new configuration is requested from the master. Setting this to null will keep the information indefinitely until the cache is cleared manually using vault.clear_cache with connection=false.

secret

The time in seconds to cache tokens/SecretIDs for. Defaults to ttl, which caches the secret for as long as it is valid, unless a new configuration is requested from the master.

server

Configures Vault server details.

url

URL of your Vault installation. Required.

verify

Configures certificate verification behavior when issuing requests to the Vault server. If unset, requests will use the CA certificates bundled with certifi.

For details, please see the requests documentation on certificate verification.

Note

In addition, this value can be set to a PEM-encoded CA certificate to use as the sole trust anchor for certificate chain verification.

Hint

This value can be set inside the minion configuration as well, from where it will take precedence.

namespace

Optional Vault namespace. Used with Vault Enterprise.

Master-only configuration

issue

Configures authentication data issued by the master to minions.

type

The type of authentication to issue to minions. Can be token or approle. Defaults to token.

To be able to issue AppRoles to minions, the master needs to be able to create new AppRoles on the configured auth mount. It is strongly encouraged to create a separate mount dedicated to minions.

approle

Configuration regarding issued AppRoles.

mount

Specifies the name of the auth mount the master manages. Defaults to salt-minions. This mount should be exclusively dedicated to the Salt master.

params

Configures the AppRole the master creates for minions. See the Vault AppRole API docs for details. If you update these params, you can update the minion AppRoles manually using the runner vault.sync_approles, but they will be updated automatically during a request by a minion as well.

token

Configuration regarding issued tokens.

role_name

Specifies the Token Role name to use for creating minion tokens. If omitted, minion tokens will be created without any role, thus being able to inherit any master token policy (including token creation capabilities).

params

Configures the tokens the master issues to minions. See the Vault Token API docs for details. To make full use of multi-use tokens, you should configure a cache that survives a single session (e.g. disk).

Important

If unset, the master issues single-use tokens to minions, which can be quite expensive.

allow_minion_override_params

Whether to allow minions to request to override parameters for issuing credentials. See issue_params.

wrap

The time a minion has to unwrap a wrapped secret issued by the master. Set this to false to disable wrapping, otherwise a time string like 30s can be used. Defaults to 30s.

keys

List of keys to use to unseal the Vault server with the vault.unseal runner.

metadata

Configures metadata for the issued entities/secrets. Values can be strings or string templates.

Note

Values have to be strings, hence templated variables that resolve to lists will be concatenated to a lexicographically sorted comma-separated list (Python list.sort()).

entity

Configures the metadata associated with the minion entity inside Vault. Entities are only created when issuing AppRoles to minions.

secret

Configures the metadata associated with issued tokens/SecretIDs. They are logged in plaintext to the Vault audit log.

policies

assign

List of policies that are assigned to issued minion authentication data, either token or AppRole. They can be static strings or string templates.

Defaults to [saltstack/minions, saltstack/{minion}].

cache_time

Number of seconds compiled templated policies are cached on the master. This is important when using pillar values in templates, since compiling the pillar is an expensive operation.

Note

Only effective when issuing tokens to minions. Token policies need to be compiled every time a token is requested, while AppRole-associated policies are written to Vault configuration the first time authentication data is requested (they can be refreshed on demand by running the vault.sync_approles runner).

They will also be refreshed in case other issuance parameters are changed, either on the master or the minion (if allow_minion_override_params is True).

refresh_pillar

Whether to refresh the minion pillar when compiling templated policies that contain pillar variables. Only effective when issuing tokens to minions (see note on policies:cache_time).

Possible values:

null

(default) Only compile the pillar when no cached pillar is found.

false

Never compile the pillar. This means templated policies that contain pillar values are skipped if no cached pillar is found.

true

Always compile the pillar. This can cause additional strain on the master since the compilation is costly.

Note

Hardcoded to True when issuing AppRoles.

Using cached pillar data only (refresh_pillar=False) might cause the policies to be out of sync. If there is no cached pillar data available for the minion, pillar templates will fail to render at all.

If you use pillar values for templating policies and do not disable refreshing pillar data, make sure the relevant values are not sourced from Vault (ext_pillar, sdb) or from a pillar sls file that uses the vault execution/sdb module. Although this will often work when cached pillar data is available, if the master needs to compile the pillar data during policy rendering, all Vault modules will be broken to prevent an infinite loop.

Minion-only configuration

Note

In addition to the following minion-only values, auth:token_lifecycle and server:verify can be set on the minion as well, even if it pulls its configuration from a master.

config_location

Override the source of the Vault configuration for the minion. By default, this extension will try to determine if it needs to request the connection details from the master or from the local config, depending on the minion running in local or master-connected mode. This option will force the extension to use the connection details from the master or the local config, regardless of circumstances. Allowed values: master, local.

issue_params

Request overrides for token/AppRole issuance. This needs to be allowed on the master by setting issue:allow_minion_override_params to true. See the master configuration issue:token:params or issue:approle:params for reference.

All configuration parameters with defaults

vault:
  auth:
    approle_mount: approle
    approle_name: salt-master
    method: token
    role_id: <required if auth:method == approle>
    secret_id: null
    token: <required if auth:method == token>
    token_lifecycle:
      minimum_ttl: 10
      renew_increment: null
  cache:
    backend: session
    config: 3600
    kv_metadata: connection
    secret: ttl
  config_location: <variable, depends on running scope>
  issue:
    allow_minion_override_params: false
    type: token
    approle:
      mount: salt-minions
      params:
        bind_secret_id: true
        secret_id_num_uses: 1
        secret_id_ttl: 60
        token_explicit_max_ttl: 60
        token_num_uses: 10
        secret_id_bound_cidrs: null
        token_ttl: null
        token_max_ttl: null
        token_no_default_policy: false
        token_period: null
        token_bound_cidrs: null
    token:
      role_name: null
      params:
        explicit_max_ttl: null
        num_uses: 1
        ttl: null
        period: null
        no_default_policy: false
        renewable: true
    wrap: 30s
  issue_params: {}
  keys: []
  metadata:
    entity:
      minion-id: '{minion}'
    secret:
      saltstack-jid: '{jid}'
      saltstack-minion: '{minion}'
      saltstack-user: '{user}'
  policies:
    assign:
      - saltstack/minions
      - saltstack/{minion}
    cache_time: 60
    refresh_pillar: null
  server:
    url: <required, e. g. https://vault.example.com:8200>
    namespace: null
    verify: null