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.

`client`¶

Added in version 1.1.0.

Configures Vault API client behavior. By default, the client retries requests with a backoff strategy, unless the response includes a Retry-After header, which is respected. Connection errors as well as responses with the status codes 412, 429, 500, 502, 503, 504 are retried.

connect_timeout¶

Added in version 1.1.0.

The number of seconds to wait for a connection to be established. Defaults to 9.2.

read_timeout¶

Added in version 1.1.0.

The number of seconds to wait between packets sent by the server. Defaults to 30.

max_retries¶

Added in version 1.1.0.

The maximum number of retries (not including the initial request) before raising an exception. Set this to 0 to disable retry behavior. Defaults to 5. Maximum: 10.

backoff_factor¶

Added in version 1.1.0.

A backoff factor (in seconds) to use between retry attempts when applying the backoff strategy (based on the Fibonacci sequence). Defaults to 0.1. Maximum: 3.0

Hint

The effective sleep time before the nth retry is given by:

{backoff_factor} * {Fibonacci(n+3)}

The default values thus result in the following sleep times (in seconds), without accounting for backoff_jitter and only if the response did not include the Retry-After header:

[initial request] 0.2 [1st] 0.3 [2nd] 0.5 [3rd] 0.8 [4th] 1.3 [5th]

If we did not receive a response (connection/read error), the first retry is executed immediately, thus the following sleep times are in effect by default:

[initial request] 0 [1st] 0.2 [2nd] 0.3 [3rd] 0.5 [4th] 0.8 [5th]

backoff_max¶

Added in version 1.1.0.

A cap for the effective sleep time between retries. Defaults to 10.0. Maximum: 60.0.

backoff_jitter¶

Added in version 1.1.0.

A maximum number of seconds to randomize the effective sleep time between retries by. Defaults to 0.2. Maximum: 5.0

retry_post¶

Added in version 1.1.0.

Whether to retry requests that are potentially non-idempotent (POST, PATCH). Defaults to False.

Note

HTTP 429 responses are always retried, regardless of HTTP verb.

retry_status¶

Added in version 1.1.0.

A list of HTTP status codes which should be retried. Defaults to [412, 500, 502, 503, 504].

Note

HTTP 429 is always retried, regardless of HTTP verb and whether it is present in this list. It is recommended to ensure the Retry-After header is sent by Vault to optimize the spent resources. See respect_retry_after for details.

respect_retry_after¶

Added in version 1.1.0.

Whether to respect the Retry-After header sent by Vault, usually when a rate limit has been hit. Defaults to True.

Hint

This header is not sent by default and must be enabled explicitly via enable_rate_limit_response_headers.

retry_after_max¶

Added in version 1.1.0.

When respect_retry_after is True, limit the maximum amount of seconds the client will sleep before retrying. Set this to null (YAML/JSON)/None (Python) to disable this behavior. Defaults to 60.

`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, server:verify and client 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
  client:
    max_retries: 5
    connect_timeout: 9.2
    read_timeout: 30
    backoff_factor: 0.1
    backoff_max: 10
    backoff_jitter: 0.2
    retry_post: false
    retry_status:
      - 412
      - 500
      - 502
      - 503
      - 504
    respect_retry_after: true
    retry_after_max: 60
  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

Configuration Reference¶

General configuration¶

auth¶

approle_mount¶

approle_name¶

method¶

role_id¶

secret_id¶

token¶

token_lifecycle¶

cache¶

backend¶

clear_attempt_revocation¶

clear_on_unauthorized¶

config¶

expire_events¶

kv_metadata¶

secret¶

client¶

connect_timeout¶

read_timeout¶

max_retries¶

backoff_factor¶

backoff_max¶

backoff_jitter¶

retry_post¶

retry_status¶

respect_retry_after¶

retry_after_max¶

server¶

url¶

verify¶

namespace¶

Master-only configuration¶

issue¶

type¶

approle¶

token¶

allow_minion_override_params¶

wrap¶

keys¶

metadata¶

entity¶

secret¶

policies¶

assign¶

cache_time¶

refresh_pillar¶

Minion-only configuration¶

config_location¶

issue_params¶

All configuration parameters with defaults¶

`auth`¶

`cache`¶

`client`¶

`server`¶

`issue`¶

`keys`¶

`metadata`¶

`policies`¶

`config_location`¶

`issue_params`¶