saltext.vault.utils.vault¶

High-level utility functions for Vault (or OpenBao) interaction

saltext.vault.utils.vault.query(method: str, endpoint: str, opts: dict[str, Any], context: dict[Any, Any], payload: dict[Any, Any] | None = None, *, wrap: str | Literal[False] = False, raise_error: bool = True, safe_to_retry: bool | None = None, is_unauthd: bool = False, warn_handler: bool | Callable[[list[str]], list[str] | None] = True, **kwargs)[source]¶

Query the Vault API. Supplemental arguments to requests.request can be passed as kwargs.

method: HTTP verb to use.

Note

A literal LIST is passed through as-is and does not follow the client:list_as_get option. Use api_list() for logical list operations that respect it.
endpoint: API path to call (without leading /v1/).
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
payload: Dictionary of payload values to send, if any.
wrap: Whether to request response wrapping. Should be a time string like 30s or False (default).
raise_error: Whether to inspect the response code and raise exceptions. Defaults to True.
safe_to_retry: Added in version 1.4.0.

A boolean indicating whether this request is safe to retry (idempotent) or not. If not provided, defaults to guessing based on the HTTP method. Unsafe requests are not retried, unless client:retry_post is enabled.
is_unauthd: Whether the queried endpoint is an unauthenticated one and hence does not deduct a token use. Only relevant for endpoints not found in sys. Defaults to False.
warn_handler: Added in version 1.9.0.

Boolean or callable to handle Vault-emitted warnings. Defaults to true, meaning all emitted warnings are logged. Set this to false to silence any warnings. Set this to a callable that takes a list of warnings and optionally returns a list of warnings to log.

saltext.vault.utils.vault.query_raw(method: str, endpoint: str, opts: dict[str, Any], context: dict[Any, Any], payload: dict[Any, Any] | None = None, *, wrap: str | Literal[False] = False, retry: bool = True, is_unauthd: bool = False, safe_to_retry: bool | None = None, **kwargs)[source]¶

Query the Vault API, returning the raw response object. Supplemental arguments to requests.request can be passed as kwargs.

method: HTTP verb to use.

Note

A literal LIST is passed through as-is and does not follow the client:list_as_get option.
endpoint: API path to call (without leading /v1/).
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
payload: Dictionary of payload values to send, if any.
retry: Retry the query with cleared cache in case the permission was denied (to check for revoked cached credentials). Defaults to True.

Note

Affects handling of 403 Forbidden responses by this function and is independent from client settings.
wrap: Whether to request response wrapping. Should be a time string like 30s or False (default).
safe_to_retry: Added in version 1.4.0.

A boolean indicating whether this request is safe to retry (idempotent) or not. If not provided, defaults to guessing based on the HTTP method. Unsafe requests are not retried, unless client:retry_post is enabled.
is_unauthd: Whether the queried endpoint is an unauthenticated one and hence does not deduct a token use. Only relevant for endpoints not found in sys. Defaults to False.

saltext.vault.utils.vault.api_get(endpoint: str, opts: dict[str, Any], context: dict[Any, Any], payload: dict[Any, Any] | None = None, *, wrap: str | Literal[False] = False, raise_error: bool = True, safe_to_retry: bool | None = None, is_unauthd: bool = False, warn_handler: bool | Callable[[list[str]], list[str] | None] = True, **kwargs)[source]¶

Query the Vault API using a GET request. Supplemental arguments to requests.request can be passed as kwargs.

Added in version 1.9.0.

endpoint: API path to call (without leading /v1/).
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
payload: Dictionary of query parameters to send, if any. They are URL-encoded automatically.
wrap: Whether to request response wrapping. Should be a time string like 30s or False (default).
raise_error: Whether to inspect the response code and raise exceptions. Defaults to True.
safe_to_retry: A boolean indicating whether this request is safe to retry (idempotent) or not. If not provided, defaults to guessing based on the HTTP method. Unsafe requests are not retried, unless client:retry_post is enabled.
is_unauthd: Whether the queried endpoint is an unauthenticated one and hence does not deduct a token use. Only relevant for endpoints not found in sys. Defaults to False.
warn_handler: Boolean or callable to handle Vault-emitted warnings. Defaults to true, meaning all emitted warnings are logged. Set this to false to silence any warnings. Set this to a callable that takes a list of warnings and optionally returns a list of warnings to log.

saltext.vault.utils.vault.api_list(endpoint: str, opts: dict[str, Any], context: dict[Any, Any], payload: dict[Any, Any] | None = None, *, wrap: str | Literal[False] = False, raise_error: bool = True, safe_to_retry: bool | None = None, is_unauthd: bool = False, warn_handler: bool | Callable[[list[str]], list[str] | None] = True, **kwargs)[source]¶

Query the Vault API using a logical list operation. Supplemental arguments to requests.request can be passed as kwargs.

By default, this uses the LIST HTTP method. When client:list_as_get is enabled, it issues a GET request with the list=true query parameter instead.

Added in version 1.9.0.

endpoint: API path to call (without leading /v1/).
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
payload: Dictionary of query parameters to send, if any. They are URL-encoded automatically.
wrap: Whether to request response wrapping. Should be a time string like 30s or False (default).
raise_error: Whether to inspect the response code and raise exceptions. Defaults to True.
safe_to_retry: A boolean indicating whether this request is safe to retry (idempotent) or not. If not provided, defaults to guessing based on the HTTP method. Unsafe requests are not retried, unless client:retry_post is enabled.
is_unauthd: Whether the queried endpoint is an unauthenticated one and hence does not deduct a token use. Only relevant for endpoints not found in sys. Defaults to False.
warn_handler: Boolean or callable to handle Vault-emitted warnings. Defaults to true, meaning all emitted warnings are logged. Set this to false to silence any warnings. Set this to a callable that takes a list of warnings and optionally returns a list of warnings to log.

saltext.vault.utils.vault.api_post(endpoint: str, opts: dict[str, Any], context: dict[Any, Any], payload: dict[Any, Any] | None = None, *, wrap: str | Literal[False] = False, raise_error: bool = True, safe_to_retry: bool | None = None, is_unauthd: bool = False, warn_handler: bool | Callable[[list[str]], list[str] | None] = True, **kwargs)[source]¶

Query the Vault API using a POST request. Supplemental arguments to requests.request can be passed as kwargs.

Added in version 1.9.0.

endpoint: API path to call (without leading /v1/).
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
payload: Dictionary of payload values to send as the JSON request body, if any.
wrap: Whether to request response wrapping. Should be a time string like 30s or False (default).
raise_error: Whether to inspect the response code and raise exceptions. Defaults to True.
safe_to_retry: A boolean indicating whether this request is safe to retry (idempotent) or not. If not provided, defaults to guessing based on the HTTP method. Unsafe requests are not retried, unless client:retry_post is enabled.
is_unauthd: Whether the queried endpoint is an unauthenticated one and hence does not deduct a token use. Only relevant for endpoints not found in sys. Defaults to False.
warn_handler: Boolean or callable to handle Vault-emitted warnings. Defaults to true, meaning all emitted warnings are logged. Set this to false to silence any warnings. Set this to a callable that takes a list of warnings and optionally returns a list of warnings to log.

saltext.vault.utils.vault.api_put(endpoint: str, opts: dict[str, Any], context: dict[Any, Any], payload: dict[Any, Any] | None = None, *, wrap: str | Literal[False] = False, raise_error: bool = True, safe_to_retry: bool = True, is_unauthd: bool = False, warn_handler: bool | Callable[[list[str]], list[str] | None] = True, **kwargs)[source]¶

Query the Vault API using a POST request that is marked as safe to retry by default (idempotent). Vault considers POST and PUT to be synonymous, this is the only difference to api_post(). Supplemental arguments to requests.request can be passed as kwargs.

Added in version 1.9.0.

endpoint: API path to call (without leading /v1/).
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
payload: Dictionary of payload values to send as the JSON request body, if any.
wrap: Whether to request response wrapping. Should be a time string like 30s or False (default).
raise_error: Whether to inspect the response code and raise exceptions. Defaults to True.
safe_to_retry: A boolean indicating whether this request is safe to retry (idempotent) or not. Defaults to True. Unsafe requests are not retried, unless client:retry_post is enabled.
is_unauthd: Whether the queried endpoint is an unauthenticated one and hence does not deduct a token use. Only relevant for endpoints not found in sys. Defaults to False.
warn_handler: Boolean or callable to handle Vault-emitted warnings. Defaults to true, meaning all emitted warnings are logged. Set this to false to silence any warnings. Set this to a callable that takes a list of warnings and optionally returns a list of warnings to log.

saltext.vault.utils.vault.api_patch(endpoint: str, opts: dict[str, Any], context: dict[Any, Any], payload: dict[Any, Any], *, wrap: str | Literal[False] = False, raise_error: bool = True, safe_to_retry: bool | None = None, is_unauthd: bool = False, warn_handler: bool | Callable[[list[str]], list[str] | None] = True, **kwargs)[source]¶

Query the Vault API using a PATCH request. Supplemental arguments to requests.request can be passed as kwargs.

Added in version 1.9.0.

endpoint: API path to call (without leading /v1/).
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
payload: Dictionary of payload values to send as the JSON merge patch body.
wrap: Whether to request response wrapping. Should be a time string like 30s or False (default).
raise_error: Whether to inspect the response code and raise exceptions. Defaults to True.
safe_to_retry: A boolean indicating whether this request is safe to retry (idempotent) or not. If not provided, defaults to guessing based on the HTTP method. Unsafe requests are not retried, unless client:retry_post is enabled.
is_unauthd: Whether the queried endpoint is an unauthenticated one and hence does not deduct a token use. Only relevant for endpoints not found in sys. Defaults to False.
warn_handler: Boolean or callable to handle Vault-emitted warnings. Defaults to true, meaning all emitted warnings are logged. Set this to false to silence any warnings. Set this to a callable that takes a list of warnings and optionally returns a list of warnings to log.

saltext.vault.utils.vault.api_delete(endpoint: str, opts: dict[str, Any], context: dict[Any, Any], payload: dict[Any, Any] | None = None, *, wrap: str | Literal[False] = False, raise_error: bool = True, safe_to_retry: bool | None = None, is_unauthd: bool = False, warn_handler: bool | Callable[[list[str]], list[str] | None] = True, **kwargs)[source]¶

Query the Vault API using a DELETE request. Supplemental arguments to requests.request can be passed as kwargs.

Added in version 1.9.0.

endpoint: API path to call (without leading /v1/).
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
payload: Dictionary of query parameters to send, if any. They are URL-encoded automatically.
wrap: Whether to request response wrapping. Should be a time string like 30s or False (default).
raise_error: Whether to inspect the response code and raise exceptions. Defaults to True.
safe_to_retry: A boolean indicating whether this request is safe to retry (idempotent) or not. If not provided, defaults to guessing based on the HTTP method. Unsafe requests are not retried, unless client:retry_post is enabled.
is_unauthd: Whether the queried endpoint is an unauthenticated one and hence does not deduct a token use. Only relevant for endpoints not found in sys. Defaults to False.
warn_handler: Boolean or callable to handle Vault-emitted warnings. Defaults to true, meaning all emitted warnings are logged. Set this to false to silence any warnings. Set this to a callable that takes a list of warnings and optionally returns a list of warnings to log.

saltext.vault.utils.vault.is_v2(path: str, opts: dict[str, Any], context: dict[Any, Any])[source]¶

Determines if a given secret path is KV v1 or v2.

path: Path to the secret, including mount.
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.

saltext.vault.utils.vault.read_kv(path: str, opts: dict[str, Any], context: dict[Any, Any], include_metadata: bool = False, version: int | str | None = None)[source]¶

Read secret at <path>.

path: Path to the secret, including mount.
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
metadata: If path is on a KV v2 backend, display full results, including metadata. Defaults to False.
version: Version to read. If unset, reads the latest one.

saltext.vault.utils.vault.read_kv_meta(path: str, opts: dict[str, Any], context: dict[Any, Any])[source]¶

Read secret metadata and version info at <path>. Requires KV v2.

Added in version 1.2.0.

path: Path to the secret, including mount.
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.

saltext.vault.utils.vault.write_kv(path: str, data: dict[str, Any], opts: dict[str, Any], context: dict[Any, Any])[source]¶

Write secret <data> to <path>.

path: Path to the secret, including mount.
data: Secret data to write to <path>. Has to be a mapping.
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.

saltext.vault.utils.vault.patch_kv(path: str, data: dict[str, Any], opts: dict[str, Any], context: dict[Any, Any])[source]¶

Patch secret <data> at <path>.

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

saltext.vault.utils.vault.delete_kv(path: str, opts: dict[str, Any], context: dict[Any, Any], versions: int | str | list[int | str] | None = None, all_versions: bool = False)[source]¶

Delete secret at <path>. For KV v2, versions can be specified, which is soft-deleted.

path: Path to the secret, including mount.
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
versions: List of versions to soft-delete. If no version is specified, deletes the most recent one.
all_versions: Delete all versions of the secret for KV v2. Defaults to false.

saltext.vault.utils.vault.restore_kv(path: str, opts: dict[str, Any], context: dict[Any, Any], versions: int | str | list[int | str] | None = None, all_versions: bool = False)[source]¶

Restore secret versions at <path>. Requires KV v2.

path: Path to the secret, including mount.
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
versions: List of versions to restore. If no version is specified, restores the most recent one.
all_versions: Restore all versions of the secret for KV v2. Defaults to false.

saltext.vault.utils.vault.destroy_kv(path: str, versions: int | str | list[int | str] | None, opts: dict[str, Any], context: dict[Any, Any], all_versions: bool = False)[source]¶

Destroy secret <versions> at <path>. Requires KV v2.

path: Path to the secret, including mount.
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.
all_versions: Restore all versions of the secret for KV v2. Defaults to false.

saltext.vault.utils.vault.wipe_kv(path: str, opts: dict[str, Any], context: dict[Any, Any])[source]¶

Completely remove all version history and data at <path>. Requires KV v2.

Added in version 1.2.0.

path: Path to the secret, including mount.
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.

saltext.vault.utils.vault.list_kv(path: str, opts: dict[str, Any], context: dict[Any, Any])[source]¶

List secrets at <path>.

path: Path to the secret, including mount.
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.

saltext.vault.utils.vault.render_identity_template(tpl: str, opts: dict[str, Any], context: dict[Any, Any]) → str | None[source]¶

Render an identity template based on the currently active token. Example: foo/{{identity.entity.metadata.bar}}.

tpl: (Possible) template string.
opts: Pass __opts__ from the module.
context: Pass __context__ from the module.

class saltext.vault.utils.vault.LazyIdentityContext(client: AuthenticatedVaultClient)[source]¶: Simulates an identity metadata dictionary. Requests data from Vault once an item is accessed.