`vault`¶

SSH wrapper for the vault execution module.

See there for documentation.

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

Added in version 1.0.0.

Delete Vault caches. Ensures 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 keeps the connection cache, regardless of connection.

saltext.vault.wrapper.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.wrapper.vault.delete_secret(path, *args, all_versions=False, **_)¶

Delete secret at <path>. If <path> is on KV v2, the secret is 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: 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.wrapper.vault.destroy_secret(path, *args, all_versions=False, **_)¶

Destroy specified secret versions at <path>. This makes a secret version unrecoverable. On KV v1, there is no functional difference to delete because the backend does not support versioning. Specifying versions fails there.

Changed in version 1.8.0: KV v1 secrets are now deleted instead of failing.

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: Path to the secret, including mount.
all_versions: Added in version 1.2.0.

Destroy 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.wrapper.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

saltext.vault.wrapper.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: Path to the secret, including mount.
default: When the path is not found, an exception is 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 only returns 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.wrapper.vault.patch_raw(path, raw)¶

Added in version 1.8.0.

Patch raw data at <path>.

CLI Example:

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

Required policy: see patch_secret()

path: Path to the secret, including mount.
raw: Secret data to patch into <path>. Has to be a mapping. Keys set to null (JSON/YAML)/None (Python) are deleted.

saltext.vault.wrapper.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 uses 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) are 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: Path to the secret, including mount.

saltext.vault.wrapper.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.wrapper.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: Name of the policy to delete.

saltext.vault.wrapper.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: Name of the policy to fetch.

saltext.vault.wrapper.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: Name of the policy to create/update.
rules: Rules to write, formatted as in-line HCL.

saltext.vault.wrapper.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.wrapper.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: Path to the secret, including mount.
key: Field of secret at path to read. If unspecified, returns the whole dataset.
metadata: If path is on a KV v2 backend, display full results, including metadata. Only respected if key is not set. Defaults to False.
default: Instead of raising an exception, return this value when path is not found or the secret at path does not contain key.
version: Version to read. If unset, reads the latest one.

Added in version 1.2.0.

saltext.vault.wrapper.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: Path to the secret, including mount.

saltext.vault.wrapper.vault.restore_secret(path, *versions, all_versions=False, **_)¶

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: 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.wrapper.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.

Note

This is only relevant on minions that receive issued credentials from the master. On locally configured minions, this does nothing.

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.wrapper.vault.wipe_secret(path)¶

Added in version 1.2.0.

Remove all version history and data for the secret at <path>. On KV v1, there is no functional difference to delete because the backend does not support versioning.

Changed in version 1.8.0: KV v1 secrets are now deleted instead of failing.

CLI Example:

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

Required policy:

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

saltext.vault.wrapper.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: Path to the secret, including mount.
raw: Secret data to write to <path>. Has to be a mapping.

saltext.vault.wrapper.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: Path to the secret, including mount.

vault¶

`vault`¶