HVAC: HashiCorp Vault API Client

Warnings

• breaking hvac v2.0.0 dropped support for Python 3.6 and 3.7. It also removed support for Vault versions 1.6.x through 1.10.x and previously deprecated methods and code paths. [cite: 2.0.0 release notes]
  Fix: Upgrade Python to 3.8+ and ensure Vault server is 1.11.x or later. Review changelog for specific method removals.
• breaking The `Client.write_data` method's default behavior changed in `v2.1.0` related to a bug fix for a 'potentially dangerous default.' This could alter behavior for users relying on previous default parameters. [cite: 2.1.0 release notes]
  Fix: Explicitly specify all parameters for `Client.write_data` to ensure desired behavior, rather than relying on implicit defaults.
• deprecated The `certificate` parameter for `create_ca_certificate_role` will no longer accept file paths in `v3.0.0`. [cite: v1.1.0 release notes]
  Fix: Pass certificate data as a string directly, rather than a file path, to `create_ca_certificate_role`.
• deprecated The default value of `raise_on_deleted_version` is planned to change from `True` to `False` in a future major release, impacting how deleted secret versions are handled during reads. [cite: v1.1.0 release notes]
  Fix: Explicitly set `raise_on_deleted_version=True` or `False` when calling `read_secret_version` to ensure consistent behavior regardless of the upcoming default change.
• gotcha For KV v2 secret engines, the generic `client.list()` method does not work as expected for listing paths/folders. You must use `client.secrets.kv.v2.list_secrets()`.
  Fix: Always use `client.secrets.kv.v2.list_secrets(mount_point='your_mount', path='your/path/')` for listing secrets and paths in KV v2 engines.
• gotcha Vault currently defaults the `secret/` path to KV secrets engine version 2 in 'dev' mode. Outside of 'dev' mode (from Vault v1.1.0 onwards), no KV secrets engine is mounted by default at `secret/` and must be explicitly enabled.
  Fix: Ensure the KV secrets engine is explicitly enabled and configured at your desired mount point in production Vault environments before attempting to interact with it via `hvac`.
• gotcha New exception types (`hvac.exceptions.VaultPermissionDenied` for 405 and `hvac.exceptions.VaultPreconditionFailed` for 412) were added in v2.2.0. If you were catching generic exceptions for these HTTP status codes, your error handling might need updates. [cite: v2.2.0 release notes, 18]
  Fix: Update exception handling to catch `VaultPermissionDenied` and `VaultPreconditionFailed` for more specific error management if desired.

Install

• pip install hvac Base installation
• pip install "hvac[parser]" With HCL parser support

Imports

• Client

  import hvac
  client = hvac.Client(...)

  The primary interaction with Vault is through an instance of the hvac.Client class.

Quickstart

This quickstart demonstrates how to initialize the `hvac.Client`, authenticate using a token (read from an environment variable), and perform basic CRUD operations (create, read, delete) on a KV v2 secret engine. Ensure a Vault server is running and accessible at `VAULT_ADDR` with a valid `VAULT_TOKEN` for authentication. The KV v2 secret engine should be enabled at the `secret` mount point.

import os
import hvac

# Configure these environment variables or replace with direct values
VAULT_ADDR = os.environ.get('VAULT_ADDR', 'http://127.0.0.1:8200')
VAULT_TOKEN = os.environ.get('VAULT_TOKEN', 'root-token-for-dev')

try:
    client = hvac.Client(url=VAULT_ADDR, token=VAULT_TOKEN)

    if not client.is_authenticated():
        raise Exception("HVAC client not authenticated. Check VAULT_ADDR and VAULT_TOKEN.")

    print("Client authenticated successfully.")

    # Example: Write a secret to KV v2 engine
    mount_point = 'secret'
    path = 'my-app/config'
    secret_data = {'api_key': 'super-secret-key-123', 'environment': 'dev'}

    print(f"\nWriting secret to {mount_point}/{path}...")
    client.secrets.kv.v2.create_or_update_secret(
        mount_point=mount_point,
        path=path,
        secret=secret_data,
    )
    print("Secret written.")

    # Example: Read the secret from KV v2 engine
    print(f"\nReading secret from {mount_point}/{path}...")
    read_response = client.secrets.kv.v2.read_secret_version(
        mount_point=mount_point,
        path=path
    )

    retrieved_data = read_response['data']['data']
    print(f"Retrieved secret: {retrieved_data}")

    # Example: Delete the secret
    print(f"\nDeleting secret {mount_point}/{path}...")
    client.secrets.kv.v2.delete_metadata_and_all_versions(
        mount_point=mount_point,
        path=path
    )
    print("Secret deleted.")

except Exception as e:
    print(f"An error occurred: {e}")