/ 
WWW-OpenBao-0.001
/ WWW::OpenBao

NAME

WWW::OpenBao - HTTP client for OpenBao / HashiCorp Vault API

VERSION

version 0.001

SYNOPSIS

use WWW::OpenBao;

my $bao = WWW::OpenBao->new(
  endpoint => $ENV{OPENBAO_ADDR}  // 'http://127.0.0.1:8200',
  token    => $ENV{OPENBAO_TOKEN} // '',
  kv_mount => 'secret',
);

$bao->write_secret('app/db', { user => 'app', pass => 'hunter2' });
my $creds = $bao->read_secret('app/db');
my $keys  = $bao->list_secrets('app/');
$bao->delete_secret('app/db');

$bao->login_k8s( role => 'my-app' );  # sets $bao->token

DESCRIPTION

WWW::OpenBao is a minimal HTTP client for OpenBao and HashiCorp Vault. It covers the day-to-day surface used by application code: KV v2 secret read/write/list/delete, Kubernetes ServiceAccount login, and a handful of sys/* bootstrap helpers (health, init, unseal, enable_engine).

It is intentionally small — no caching, no lease renewal, no policy management. If you need those, reach for a heavier client; if you just want to talk to Vault/OpenBao from Perl, this is enough.

All methods croak on non-2xx responses, with the single exception of read_secret which returns undef on 404 so callers can treat "secret not found" as a soft miss.

endpoint

Required. Base URL of the Vault/OpenBao server, e.g. http://127.0.0.1:8200. No trailing slash.

token

Vault token used for the X-Vault-Token header. Writable — "login_k8s" overwrites it on success.

kv_mount

Mount path of the KV v2 engine. Defaults to secret.

read_secret($path)

Returns the data.data hashref for a KV v2 secret, or undef if the path does not exist.

write_secret($path, \%data)

Writes (creates a new version of) a KV v2 secret. Returns the decoded response.

delete_secret($path)

Deletes the secret and its metadata (all versions). This is the destructive DELETE /metadata/... form, not the soft-delete.

list_secrets($path)

Returns an arrayref of keys at the given KV v2 metadata path. Empty arrayref if the path is missing.

secret_exists($path)

True if metadata exists for the given path, false otherwise. Does not fetch the secret data.

login_k8s(role => $role, jwt => $jwt)

Performs a Kubernetes ServiceAccount login against v1/auth/kubernetes/login. role is required. jwt defaults to the in-pod ServiceAccount token at /var/run/secrets/kubernetes.io/serviceaccount/token. On success the returned client_token is stored in "token" and the full auth hashref is returned.

health

Returns the parsed /v1/sys/health response, or undef if the request fails (sealed/uninitialised servers return non-2xx — that is fine here, the caller usually just wants to know something answered).

init(secret_shares => $n, secret_threshold => $n)

Initialises an uninitialised server. Both arguments default to 1. Use this for dev/test only.

unseal($key)

Submits a single unseal key share.

enable_engine($path, $type)

Mounts a secrets engine at $path with the given $type (e.g. kv-v2).

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-www-openbao/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudss.us/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.