vault_secret

Interface with the Vault (or OpenBao) KV secret backend.

Added in version 1.9.0: Functions in this module were extracted from the vault execution module.

Changed in version 1.9.0: The previous implementation swallowed any kind of error and returned False (or the default argument, if available).

Calls to this module only catch select Vault API errors and raise CommandExecutionError (or return the default argument, if available) instead of failing silently.

Also, read() made default the third positional parameter, replacing metadata, and made metadata and version keyword-only arguments.

list lost its keys_only parameter, which only served for backwards-compatibility.

Important

This module requires the general Vault setup.

saltext.vault.modules.vault_secret.read(path, key=None, default=salt.defaults.NOT_SET, *, metadata=False, version=None, **_)

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

Changed in version 1.9.0: Changed parameter order versus vault.read_secret:

• default became the third positional argument, replacing metadata.

• metadata and version became keyword-only arguments

CLI Example:

salt '*' vault_secret.read salt/kv/secret

Required policy:

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

# OR (!) for KV v1
path "<mount>/<secret>" {
    capabilities = ["read"]
}

path

Path to the secret, including mount.

key

Field of secret at path to read. If unspecified, returns the whole dataset.

default

Instead of raising an exception, return this value when path is not found or the secret at path does not contain key.

metadata

If path is on a KV v2 backend, display full results, including metadata. Only respected if key is not set. Defaults to False.

version

Version to read. If unset, reads the latest one.

saltext.vault.modules.vault_secret.read_meta(path)

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

CLI Example:

salt '*' vault_secret.read_meta salt/kv/secret

Required policy:

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

path

Path to the secret, including mount.

saltext.vault.modules.vault_secret.write(path, **kwargs)

Set secret dataset at <path>. Fields are specified as arbitrary keyword arguments.

CLI Example:

salt '*' vault_secret.write "secret/my/secret" user="foo" password="bar"

Required policy:

# KV v2
path "<mount>/data/<secret>" {
    capabilities = ["create", "update"]
}

# OR (!) for KV v1
path "<mount>/<secret>" {
    capabilities = ["create", "update"]
}

path

Path to the secret, including mount.

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

Set raw data at <path>.

CLI Example:

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

Required policy: see write()

path

Path to the secret, including mount.

raw

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

saltext.vault.modules.vault_secret.patch(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_secret.patch "secret/my/secret" password="baz"

Required policy:

# KV v2: Proper patching
path "<mount>/data/<secret>" {
    capabilities = ["patch"]
}

# OR (!), for very old KV v2 releases:
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.modules.vault_secret.patch_raw(path, raw)

Patch raw data at <path>.

CLI Example:

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

Required policy: see patch()

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.modules.vault_secret.list_(path, default=salt.defaults.NOT_SET)

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

Changed in version 1.9.0: Dropped keys_only parameter versus vault.list_secrets.

CLI Example:

salt '*' vault_secret.list "secret/my/"

Required policy:

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

# OR (!) for KV v1
path "<mount>/<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.

saltext.vault.modules.vault_secret.delete(path, *versions, all_versions=False, **_)

Delete secret at <path>. If <path> is on KV v2, the secret is soft-deleted.

CLI Example:

salt '*' vault_secret.delete "secret/my/secret"
salt '*' vault_secret.delete "secret/my/secret" 1 2 3
salt '*' vault_secret.delete "secret/my/secret" all_versions=true

Required policy:

# KV v2, delete most recent version
path "<mount>/data/<secret>" {
    capabilities = ["delete"]
}

# KV v2, delete older version(s)
# all_versions=True additionally requires the policy for vault_secret.read_meta
path "<mount>/delete/<secret>" {
    capabilities = ["update"]
}

# OR (!) for KV v1
path "<mount>/<secret>" {
    capabilities = ["delete"]
}

path

Path to the secret, including mount.

all_versions

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

Note

For KV v2, you can specify versions to soft-delete as supplemental positional arguments.

saltext.vault.modules.vault_secret.restore(path, *versions, all_versions=False, **_)

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

CLI Example:

salt '*' vault_secret.restore secret/my/secret 1 2

Required policy:

# KV v2 only.
# all_versions=True or defaulting to the most recent version additionally
# requires the policy for vault_secret.read_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.modules.vault_secret.destroy(path, *versions, 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.

CLI Example:

salt '*' vault_secret.destroy "secret/my/secret"
salt '*' vault_secret.destroy "secret/my/secret" 1 2
salt '*' vault_secret.destroy "secret/my/secret" all_versions=true

Required policy:

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

# OR (!) for KV v1 (same as `vault_secret.delete`)
path "<mount>/<secret>" {
    capabilities = ["delete"]
}

path

Path to the secret, including mount.

all_versions

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. If no version was specified, defaults to the most recent one.

saltext.vault.modules.vault_secret.wipe(path)

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.

CLI Example:

salt '*' vault_secret.wipe "secret/my/secret"

Required policy:

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

# OR (!) for KV v1 (same as `vault_secret.delete`)
path "<mount>/<secret>" {
    capabilities = ["delete"]
}