vault

Interface with a Vault server and the KV secret backend.

Important

This module requires the general Vault setup.

saltext.vault.modules.vault.read_secret(path, key=None, metadata=False, default=salt.defaults.NOT_SET, version=None)

Return the value of <key> at <path> in vault, or entire secret.

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"]
}

path

The path to the secret, including mount.

key

The data field at <path> to read. If unspecified, returns the whole dataset.

metadata

If using KV v2 backend, display full results, including metadata. Defaults to False.

default

When the path or path/key combination is not found, an exception will be raised, unless a default is provided here.

version

The version to read. If unset, reads the latest one.

Added in version 1.2.0.

saltext.vault.modules.vault.read_secret_meta(path)

Added in version 1.2.0.

Return secret metadata and versions for <path>. Requires KV v2.

CLI Example:

salt '*' vault.read_secret_meta salt/kv/secret

Required policy:

path "<mount>/metadata/<secret>" {
    capabilities = ["read"]
}

path

The path to the secret, including mount.

saltext.vault.modules.vault.write_secret(path, **kwargs)

Set secret dataset at <path>. 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"]
}

path

The path to the secret, including mount.

saltext.vault.modules.vault.write_raw(path, raw)

Set raw data at <path>.

CLI Example:

salt '*' vault.write_raw "secret/my/secret" '{"user":"foo","password": "bar"}'

Required policy: see write_secret()

path

The path to the secret, including mount.

raw

Secret data to write to <path>. Has to be a mapping.

saltext.vault.modules.vault.patch_secret(path, **kwargs)

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"]
}

path

The path to the secret, including mount.

saltext.vault.modules.vault.delete_secret(path, *args, **kwargs)

Delete secret at <path>. 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
salt '*' vault.delete_secret "secret/my/secret" all_versions=true

Required policy:

path "<mount>/<secret>" {
    capabilities = ["delete"]
}

# or KV v2
path "<mount>/data/<secret>" {
    capabilities = ["delete"]
}

# KV v2 versions
# all_versions=True additionally requires the policy for vault.read_secret_meta
path "<mount>/delete/<secret>" {
    capabilities = ["update"]
}

path

The path to the secret, including mount.

all_versions

Added in version 1.2.0.

Delete all versions of the secret for KV v2. Can only be passed as a keyword argument. Defaults to false.

Added in version 1.0.0: For KV v2, you can specify versions to soft-delete as supplemental positional arguments.

saltext.vault.modules.vault.restore_secret(path, *versions, **kwargs)

Added in version 1.2.0.

Restore specific versions of a secret path. Only supported on Vault KV v2.

CLI Example:

salt '*' vault.restore_secret secret/my/secret 1 2

Required policy:

# all_versions=True or defaulting to the most recent version additionally
# requires the policy for vault.read_secret_meta
path "<mount>/undelete/<secret>" {
    capabilities = ["update"]
}

path

The path to the secret, including mount.

all_versions

Restore all versions of the secret for KV v2. Can only be passed as a keyword argument. Defaults to false.

You can specify versions to restore as supplemental positional arguments. If no version is specified, tries to restore the latest version, and if the latest version has not been deleted, fails.

saltext.vault.modules.vault.destroy_secret(path, *args, **kwargs)

Destroy specified secret versions at <path>. Only supported on Vault KV v2.

CLI Example:

salt '*' vault.destroy_secret "secret/my/secret"
salt '*' vault.destroy_secret "secret/my/secret" 1 2
salt '*' vault.destroy_secret "secret/my/secret" all_versions=true

Required policy:

# all_versions=True or defaulting to the most recent version additionally
# requires the policy for vault.read_secret_meta
path "<mount>/destroy/<secret>" {
    capabilities = ["update"]
}

path

The path to the secret, including mount.

all_versions

Added in version 1.2.0.

Delete all versions of the secret for KV v2. Can only be passed as a keyword argument. Defaults to false.

You can specify versions to destroy as supplemental positional arguments.

Changed in version 1.2.0: If no version was specified, defaults to the most recent one.

saltext.vault.modules.vault.wipe_secret(path)

Added in version 1.2.0.

Remove all version history and data for the secret at <path>. Requires KV v2.

CLI Example:

salt '*' vault.wipe_secret "secret/my/secret"

Required policy:

path "<mount>/metadata/<secret>" {
    capabilities = ["delete"]
}

saltext.vault.modules.vault.list_secrets(path, default=salt.defaults.NOT_SET, keys_only=None)

List secret keys at <path>. The path should end with a trailing slash.

CLI Example:

salt '*' vault.list_secrets "secret/my/"

Required policy:

path "<mount>/<path>" {
    capabilities = ["list"]
}

# or KV v2
path "<mount>/metadata/<path>" {
    capabilities = ["list"]
}

path

The path to the secret, including mount.

default

When the path is not found, an exception will be raised, unless a default is provided here.

keys_only

Added in version 1.0.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 currently defaults to False. Beginning with version 2 of this extension, the default will change to True.

saltext.vault.modules.vault.clear_cache(connection=True, session=False)

Added in version 1.0.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

connection

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.

session

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.

saltext.vault.modules.vault.clear_token_cache()

Deprecated since version 1.0.0.

Changed in version 1.0.0: This is now an alias for vault.clear_cache with connection=True and session=False (the defaults).

Delete minion Vault token cache.

CLI Example:

salt '*' vault.clear_token_cache

saltext.vault.modules.vault.policy_fetch(policy)

Added in version 1.0.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"]
}

policy

The name of the policy to fetch.

saltext.vault.modules.vault.policy_write(policy, rules)

Added in version 1.0.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"]
}

policy

The name of the policy to create/update.

rules

Rules to write, formatted as in-line HCL.

saltext.vault.modules.vault.policy_delete(policy)

Added in version 1.0.0.

Delete an ACL policy. Returns False if the policy does not exist.

CLI Example:

salt '*' vault.policy_delete salt_minion

Required policy:

path "sys/policy/<policy>" {
    capabilities = ["delete"]
}

policy

The name of the policy to delete.

saltext.vault.modules.vault.policies_list()

Added in version 1.0.0.

List all ACL policies.

CLI Example:

salt '*' vault.policies_list

Required policy:

path "sys/policy" {
    capabilities = ["read"]
}

saltext.vault.modules.vault.query(method, endpoint, payload=None)

Added in version 1.0.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

method

HTTP method to use.

endpoint

Vault API endpoint to issue the request against. Do not include /v1/.

payload

Optional dictionary to use as JSON payload.

saltext.vault.modules.vault.update_config(keep_session=False)

Added in version 1.0.0.

Attempt to update the cached configuration without clearing the currently active Vault session.

CLI Example:

salt '*' vault.update_config

keep_session

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.

saltext.vault.modules.vault.get_server_config()

Added in version 1.0.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