vault-kv-client

vault-kv-client is a small, typed, and production-friendly helper library for working with HashiCorp Vault KV engines through hvac.

It focuses on the common parts teams end up re-implementing around Vault:

• KV v1 and v2 support with automatic mount version detection
• Token, AppRole, Kubernetes, and Vault JWT/OIDC authentication
• Enterprise namespace support
• Recursive listing and secret copy helpers
• Optional in-memory read caching
• Environment-driven bootstrap for CI, Kubernetes, and legacy Airflow deployments

Installation

pip install vault-kv-client

With uv:

uv add vault-kv-client

With Poetry:

poetry add vault-kv-client

Quick Start

from vault_kv_client import VaultAuth, VaultManager, VaultSettings

settings = VaultSettings(
    addr="https://vault.example.com",
    verify=True,
    namespace=None,
)

auth = VaultAuth(token="s.xxxxx")
client = VaultManager(settings=settings, auth=auth)

secret = client.get_secret("kv", "apps/my-service")
print(secret["username"])

Environment-driven bootstrap is also available:

from vault_kv_client import get_default_manager

client = get_default_manager()
secret = client.get_secret("kv", "apps/my-service")

Public API

Root package exports:

• VaultManager
• VaultSettings
• VaultAuth
• VaultJWTAuth
• VaultKubernetesAuth
• VaultClientError
• VaultNotConfiguredError
• VaultDependencyError
• SecretNotFoundError
• get_default_manager()
• get_creds()

Core methods:

• get_secret(mount_point, path, kv_version=None)
• upsert_secret(mount_point=..., path=..., secret=..., kv_version=None)
• list_secrets(mount_point, path="", kv_version=None)
• list_all_secrets(mount_point, path="", kv_version=None)
• copy_secret(source_mount=..., target_mount=..., path=...)
• clear_cache()

Authentication Modes

The library supports four mutually exclusive auth modes:

• token
• approle
• kubernetes
• jwt

Full examples are documented in docs/auth-methods.md.

Legacy Compatibility

The historical package name vault_client is still shipped as a temporary compatibility layer:

from vault_client import VaultManager

That import path now emits a DeprecationWarning. New projects should use vault_kv_client.

Documentation

Repository docs are designed for self-service onboarding:

• Getting Started
• Installation
• Auth Methods
• KV v1/v2 Behavior
• API Reference
• Migration from vault_client
• Development
• Security
• Release Process

The GitHub Pages site is generated from the same sources via MkDocs Material.

Development

python3 -m venv .venv
. .venv/bin/activate
pip install -U pip uv
uv pip install -e ".[dev]"
ruff check .
mypy src
pytest -q
mkdocs build

Security

• Never log secret payloads.
• Prefer short-lived auth flows where possible.
• Use the minimum Vault policy scope required for your application.
• Report security issues through the process described in SECURITY.md.

License

This project is licensed under the Apache License 2.0. See LICENSE.