Warning
This module will be removed from Salt in version 3009 in favor of the vault Salt Extension.
SaltStack
new
all
If you see the following error, you'll need to upgrade requests
to at least 2.4.2
<timestamp> [salt.pillar][CRITICAL][14337] Pillar render error: Failed to load ext_pillar vault: {'error': "request() got an unexpected keyword argument 'json'"}
In addition to the module configuration, it is required for the Salt master to be configured to allow peer runs in order to use the Vault integration.
Changed in version 3007.0: The vault
configuration structure has changed significantly to account
for many new features. If found, the old structure will be automatically
translated to the new one.
Please update your peer_run configuration to take full advantage of the
updated modules. The old endpoint (vault.generate_token
) will continue
to work, but result in unnecessary roundtrips once your minions have been
updated.
To allow minions to pull configuration and credentials from the Salt master, add this segment to the master configuration file:
peer_run:
.*:
- vault.get_config # always
- vault.generate_new_token # relevant when `token` == `issue:type`
- vault.generate_secret_id # relevant when `approle` == `issue:type`
Minimally required configuration:
vault:
auth:
token: abcdefg-hijklmnop-qrstuvw
server:
url: https://vault.example.com:8200
A sensible example configuration, e.g. in /etc/salt/master.d/vault.conf
:
vault:
auth:
method: approle
role_id: e5a7b66e-5d08-da9c-7075-71984634b882
secret_id: 841771dc-11c9-bbc7-bcac-6a3945a69cd9
cache:
backend: file
issue:
token:
role_name: salt_minion
params:
explicit_max_ttl: 30
num_uses: 10
policies:
assign:
- salt_minion
- salt_role_{pillar[roles]}
server:
url: https://vault.example.com:8200
The above configuration requires the following policies for the master:
# Issue tokens
path "auth/token/create" {
capabilities = ["create", "read", "update"]
}
# Issue tokens with token roles
path "auth/token/create/*" {
capabilities = ["create", "read", "update"]
}
A sensible example configuration that issues AppRoles to minions from a separate authentication endpoint (notice differing mounts):
vault:
auth:
method: approle
mount: approle # <-- mount the salt master authenticates at
role_id: e5a7b66e-5d08-da9c-7075-71984634b882
secret_id: 841771dc-11c9-bbc7-bcac-6a3945a69cd9
cache:
backend: file
issue:
type: approle
approle:
mount: salt-minions # <-- mount the salt master manages
metadata:
entity:
minion-id: '{minion}'
role: '{pillar[role]}'
server:
url: https://vault.example.com:8200
ext_pillar:
- vault: path=salt/minions/{minion}
- vault: path=salt/roles/{pillar[role]}
The above configuration requires the following policies for the master:
# List existing AppRoles
path "auth/salt-minions/role" {
capabilities = ["list"]
}
# Manage AppRoles
path "auth/salt-minions/role/*" {
capabilities = ["read", "create", "update", "delete"]
}
# Lookup mount accessor
path "sys/auth/salt-minions" {
capabilities = ["read", "sudo"]
}
# Lookup entities by alias name (role-id) and alias mount accessor
path "identity/lookup/entity" {
capabilities = ["create", "update"]
allowed_parameters = {
"alias_name" = []
"alias_mount_accessor" = ["auth_approle_0a1b2c3d"]
}
}
# Manage entities with name prefix salt_minion_
path "identity/entity/name/salt_minion_*" {
capabilities = ["read", "create", "update", "delete"]
}
# Create entity aliases – you can restrict the mount_accessor
# This might allow privilege escalation in case the salt master
# is compromised and the attacker knows the entity ID of an
# entity with relevant policies attached - although you might
# have other problems at that point.
path "identity/entity-alias" {
capabilities = ["create", "update"]
allowed_parameters = {
"id" = []
"canonical_id" = []
"mount_accessor" = ["auth_approle_0a1b2c3d"]
"name" = []
}
}
This enables you to write templated ACL policies like:
path "salt/data/minions/{{identity.entity.metadata.minion-id}}" {
capabilities = ["read"]
}
path "salt/data/roles/{{identity.entity.metadata.role}}" {
capabilities = ["read"]
}
Note
AppRole policies and entity metadata are generally not updated
automatically. After a change, you will need to synchronize
them by running vault.sync_approles
or vault.sync_entities
respectively.
All possible master configuration options 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
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
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
auth
¶Contains authentication information for the local machine.
New in version 3007.0.
The name of the AppRole authentication mount point. Defaults to approle
.
New in version 3007.0.
The name of the AppRole. Defaults to salt-master
.
Note
Only relevant when a locally configured role_id/secret_id uses response wrapping.
Currently only token
and approle
auth types are supported.
Defaults to token
.
AppRole is the preferred way to authenticate with Vault as it provides some advanced options to control the authentication process. Please see the Vault documentation for more information.
The role ID of the AppRole. Required if auth:method
== approle
.
Changed in version 3007.0: In addition to a plain string, this can also be specified as a
dictionary that includes wrap_info
, i.e. the return payload
of a wrapping request.
The secret ID of the AppRole. Only required if the configured AppRole requires it.
Changed in version 3007.0: In addition to a plain string, this can also be specified as a
dictionary that includes wrap_info
, i.e. the return payload
of a wrapping request.
Token to authenticate to Vault with. Required if auth:method
== token
.
The token must be able to create tokens with the policies that should be assigned to minions. You can still use the token auth via a OS environment variable via this config example:
vault:
auth:
method: token
token: sdb://osenv/VAULT_TOKEN
server:
url: https://vault.service.domain:8200
osenv:
driver: env
And then export the VAULT_TOKEN variable in your OS:
export VAULT_TOKEN=11111111-1111-1111-1111-1111111111111
Changed in version 3007.0: In addition to a plain string, this can also be specified as a
dictionary that includes wrap_info
, i.e. the return payload
of a wrapping request.
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.
Note
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.
Changed in version 3007.0: This used to be found in auth:token_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.
New in version 3007.0.
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).
New in version 3007.0.
When encountering an Unauthorized
response with an otherwise valid token,
flush the cache and request new credentials. Defaults to true.
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.
New in version 3007.0.
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.
New in version 3007.0.
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.
New in version 3007.0.
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
.
New in version 3007.0.
The time in seconds to cache tokens/secret IDs for. Defaults to ttl
,
which caches the secret for as long as it is valid, unless a new configuration
is requested from the master.
issue
¶Configures authentication data issued by the master to minions.
New in version 3007.0.
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 (see policy example above). It is strongly encouraged to create a separate mount dedicated to minions.
New in version 3007.0.
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 vault runner: salt-run vault.sync_approles
, but they
will be updated automatically during a request by a minion as well.
New in version 3007.0.
Configuration regarding issued tokens.
role_name
specifies the role name for minion tokens created. Optional.
Changed in version 3007.0: This used to be found in role_name
.
If omitted, minion tokens will be created without any role, thus being able to inherit any master token policy (including token creation capabilities).
Example configuration: https://www.nomadproject.io/docs/vault-integration/index.html#vault-token-role-configuration
params
configures the tokens the master issues to minions.
Changed in version 3007.0: This used to be found in auth:ttl
and auth:uses
.
The possible parameters were synchronized with the Vault nomenclature:
ttl
previously was mapped toexplicit_max_ttl
on Vault, notttl
. For the same behavior as before, you will need to setexplicit_max_ttl
now.
uses
is now callednum_uses
.
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
).
Note
If unset, the master issues single-use tokens to minions, which can be quite expensive.
Changed in version 3007.0: This used to be found in auth:allow_minion_override
.
Whether to allow minions to request to override parameters for issuing credentials.
See issue_params
below.
New in version 3007.0.
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 vault server with the
vault.unseal
runner.
metadata
¶New in version 3007.0.
Configures metadata for the issued entities/secrets. Values have to be strings and can be templated with the following variables:
{jid}
Salt job ID that issued the secret.
{minion}
The minion ID the secret was issued for.
{user}
The user the Salt daemon issuing the secret was running as.
{pillar[<var>]}
A minion pillar value that does not depend on Vault.
{grains[<var>]}
A minion grain value.
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()
).
Configures the metadata associated with the minion entity inside Vault. Entities are only created when issuing AppRoles to minions.
Configures the metadata associated with issued tokens/secret IDs. They are logged in plaintext to the Vault audit log.
policies
¶Changed in version 3007.0: This used to specify the list of policies associated with a minion token only.
The equivalent is found in assign
.
List of policies that are assigned to issued minion authentication data, either token or AppRole.
They can be static strings or string templates with
{minion}
The minion ID.
{pillar[<var>]}
A minion pillar value.
{grains[<var>]}
A minion grain value.
For pillar and grain values, lists are expanded, so salt_role_{pillar[roles]}
with [a, b]
results in salt_role_a
and salt_role_b
to be issued.
Defaults to [saltstack/minions, saltstack/{minion}]
.
New in version 3006.0: Policies can be templated with pillar values as well: salt_role_{pillar[roles]}
.
Make sure to only reference pillars that are not sourced from Vault since the latter
ones might be unavailable during policy rendering. If you use the Vault
integration in one of your pillar sls
files, all values from that file
will be absent during policy rendering, even the ones that do not depend on Vault.
Important
See Is Targeting using Grain Data Secure? for important security information. In short,
everything except grains[id]
is minion-controlled.
Note
List members which do not have simple string representations, such as dictionaries or objects, do not work and will throw an exception. Strings and numbers are examples of types which work well.
New in version 3007.0.
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
salt-run vault.sync_approles
).
They will also be refreshed in case other issuance parameters are changed (such as uses/ttl), either on the master or the minion (if allow_minion_override_params is True).
New in version 3007.0.
Whether to refresh the minion pillar when compiling templated policies that contain pillar variables. Only effective when issuing tokens to minions (see note on cache_time above).
null
(default) only compiles the pillar when no cached pillar is found.
false
never compiles the pillar. This means templated policies that
contain pillar values are skipped if no cached pillar is found.
true
always compiles 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.
server
¶Changed in version 3007.0: The values found in here were found in the vault
root namespace previously.
Configures Vault server details.
URL of your Vault installation. Required.
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.
New in version 2018.3.0.
Changed in version 3007.0: Minions again respect the master configuration value, which was changed implicitly in v3001. If this value is set in the minion configuration as well, it will take precedence.
In addition, this value can now be set to a PEM-encoded CA certificate to use as the sole trust anchor for certificate chain verification.
Optional Vault namespace. Used with Vault Enterprise.
For details please see: https://www.vaultproject.io/docs/enterprise/namespaces
New in version 3004.
Minion configuration (optional):
config_location
¶Where to get the connection details for calling vault. By default, vault will try to determine if it needs to request the connection details from the master or from the local config. This optional option will force vault to use the connection details from the master or the local config. Can only be either
master
orlocal
.New in version 3006.0.
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 configurationissue:token:params
orissue:approle:params
for reference.Changed in version 3007.0: For token issuance, this used to be found in
auth:ttl
andauth:uses
. Mind that the parameter names have been synchronized with Vault, see notes above (TLDR:ttl
=>explicit_max_ttl
,uses
=>num_uses
.
Note
auth:token_lifecycle
and server:verify
can be set on the minion as well.
New in version 3007.0.
Delete Vault caches. Will ensure the current token and associated leases are revoked by default.
The cache is organized in a hierarchy: /vault/connection/session/leases
.
(italics mark data that is only cached when receiving configuration from a master)
connection
contains KV metadata (by default), configuration and (AppRole) auth credentials.
session
contains the currently active token.
leases
contains leases issued to the currently active token like database credentials.
CLI Example:
salt '*' vault.clear_cache
salt '*' vault.clear_cache session=True
Only clear the cached data scoped to a connection. This includes configuration, auth credentials, the currently active auth token as well as leases and KV metadata (by default). Defaults to true. Set this to false to clear all Vault caches.
Only clear the cached data scoped to a session. This only includes
leases and the currently active auth token, but not configuration
or (AppRole) auth credentials. Defaults to false.
Setting this to true will keep the connection cache, regardless
of connection
.
Changed in version 3001.
Changed in version 3007.0: This is now an alias for vault.clear_cache
with connection=True
.
Delete minion Vault token cache.
CLI Example:
salt '*' vault.clear_token_cache
Delete secret at <path>. The vault policy used must allow this. If <path> is on KV v2, the secret will be soft-deleted.
CLI Example:
salt '*' vault.delete_secret "secret/my/secret"
salt '*' vault.delete_secret "secret/my/secret" 1 2 3
Required policy:
path "<mount>/<secret>" {
capabilities = ["delete"]
}
# or KV v2
path "<mount>/data/<secret>" {
capabilities = ["delete"]
}
# KV v2 versions
path "<mount>/delete/<secret>" {
capabilities = ["update"]
}
The path to the secret, including mount.
New in version 3007.0: For KV v2, you can specify versions to soft-delete as supplemental positional arguments.
New in version 3001.
Destroy specified secret versions <path>. The vault policy used must allow this. Only supported on Vault KV version 2.
CLI Example:
salt '*' vault.destroy_secret "secret/my/secret" 1 2
Required policy:
path "<mount>/destroy/<secret>" {
capabilities = ["update"]
}
The path to the secret, including mount.
You can specify versions to destroy as supplemental positional arguments. At least one is required.
New in version 3007.0.
Return the server connection configuration that's currently in use by Salt.
Contains url
, verify
and namespace
.
CLI Example:
salt '*' vault.get_server_config
List secret keys at <path>. The vault policy used must allow this. The path should end with a trailing slash.
Changed in version 3001: The default
argument has been added. When the path or path/key
combination is not found, an exception will be raised, unless a default
is provided.
CLI Example:
salt '*' vault.list_secrets "secret/my/"
Required policy:
path "<mount>/<path>" {
capabilities = ["list"]
}
# or KV v2
path "<mount>/metadata/<path>" {
capabilities = ["list"]
}
The path to the secret, including mount.
New in version 3001.
When the path is not found, an exception will be raised, unless a default is provided here.
New in version 3007.0.
This function used to return a dictionary like {"keys": ["some/", "some/key"]}
.
Setting this to True will only return the list of keys.
For backwards-compatibility reasons, this defaults to False.
Patch secret dataset at <path>. Fields are specified as arbitrary keyword arguments.
Note
This works even for older Vault versions, KV v1 and with missing
patch
capability, but will use more than one request to simulate
the functionality by issuing a read and update request.
For proper, single-request patching, requires versions of KV v2 that
support the patch
capability and the patch
capability to be available
for the path.
Note
This uses JSON Merge Patch format internally.
Keys set to null
(JSON/YAML)/None
(Python) will be deleted.
CLI Example:
salt '*' vault.patch_secret "secret/my/secret" password="baz"
Required policy:
# Proper patching
path "<mount>/data/<secret>" {
capabilities = ["patch"]
}
# OR (!), for older KV v2 setups:
path "<mount>/data/<secret>" {
capabilities = ["read", "update"]
}
# OR (!), for KV v1 setups:
path "<mount>/<secret>" {
capabilities = ["read", "update"]
}
The path to the secret, including mount.
New in version 3007.0.
List all ACL policies.
CLI Example:
salt '*' vault.policies_list
Required policy:
path "sys/policy" {
capabilities = ["read"]
}
New in version 3007.0.
Delete an ACL policy. Returns False if the policy did not exist.
CLI Example:
salt '*' vault.policy_delete salt_minion
Required policy:
path "sys/policy/<policy>" {
capabilities = ["delete"]
}
The name of the policy to delete.
New in version 3007.0.
Fetch the rules associated with an ACL policy. Returns None if the policy does not exist.
CLI Example:
salt '*' vault.policy_fetch salt_minion
Required policy:
path "sys/policy/<policy>" {
capabilities = ["read"]
}
The name of the policy to fetch.
New in version 3007.0.
Create or update an ACL policy.
CLI Example:
salt '*' vault.policy_write salt_minion 'path "secret/foo" {...}'
Required policy:
path "sys/policy/<policy>" {
capabilities = ["create", "update"]
}
The name of the policy to create/update.
Rules to write, formatted as in-line HCL.
New in version 3007.0.
Issue arbitrary queries against the Vault API.
CLI Example:
salt '*' vault.query GET auth/token/lookup-self
Required policy: Depends on the query.
You can ask the vault CLI to output the necessary policy:
vault read -output-policy auth/token/lookup-self
HTTP method to use.
Vault API endpoint to issue the request against. Do not include /v1/
.
Optional dictionary to use as JSON payload.
Return the value of <key> at <path> in vault, or entire secret.
Changed in version 3001: The default
argument has been added. When the path or path/key
combination is not found, an exception will be raised, unless a default
is provided.
CLI Example:
salt '*' vault.read_secret salt/kv/secret
Required policy:
path "<mount>/<secret>" {
capabilities = ["read"]
}
# or KV v2
path "<mount>/data/<secret>" {
capabilities = ["read"]
}
The path to the secret, including mount.
The data field at <path> to read. If unspecified, returns the whole dataset.
New in version 3001.
If using KV v2 backend, display full results, including metadata. Defaults to False.
New in version 3001.
When the path or path/key combination is not found, an exception will be raised, unless a default is provided here.
New in version 3007.0.
Attempt to update the cached configuration without clearing the currently active Vault session.
CLI Example:
salt '*' vault.update_config
Only update configuration that can be updated without creating a new login session. If this is false, still tries to keep the active session, but might clear it if the server configuration has changed significantly. Defaults to False.
Set raw data at <path>. The vault policy used must allow this.
CLI Example:
salt '*' vault.write_raw "secret/my/secret" '{"user":"foo","password": "bar"}'
Required policy: see write_secret
The path to the secret, including mount.
Secret data to write to <path>. Has to be a mapping.
Set secret dataset at <path>. The vault policy used must allow this. Fields are specified as arbitrary keyword arguments.
CLI Example:
salt '*' vault.write_secret "secret/my/secret" user="foo" password="bar"
Required policy:
path "<mount>/<secret>" {
capabilities = ["create", "update"]
}
# or KV v2
path "<mount>/data/<secret>" {
capabilities = ["create", "update"]
}
The path to the secret, including mount.