Package codes.grow.packages.vault
Class VaultClient
java.lang.Object
codes.grow.packages.vault.VaultClient
- All Implemented Interfaces:
AutoCloseable
Client for Vault.
Implements SPEC section 2.4 plus the Vault modules: auth(), kv(), transit(), database(), leases(), pki(), sys(), wrapping() and the SecretsProvider secrets(); withNamespace(String)
returns a view in a Vault Enterprise namespace. Thread-safe; create one per endpoint and close it
when done.
try (VaultClient client = VaultClient.fromEnv()) { // VAULT_ADDR / VAULT_TOKEN / GROW_HASHICORP_VAULT_*
client.kv().write("app/db", Map.of("password", "s3cret"));
KvSecret secret = client.kv().read("app/db");
}
Every I/O method has a blocking form and an ...Async form returning CompletableFuture.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classBuilder that configures and creates a client in one chain. -
Method Summary
Modifier and TypeMethodDescriptionauth()Logins, token self-service and token renewal.static VaultClient.Builderbuilder()Starts a client builder.voidclose()Stops token renewers, managed leases (revoking those withrevokeOnStop) and secret watchers, then releases the transport.config()Returns the configuration.static VaultClientcreate(VaultConfig config) Creates a client.database()The database engine on mountdatabase.The database engine on a mount.static VaultClientfromEnv()Creates a client from the SDK and vendor environment variables (GROW_HASHICORP_VAULT_*thenVAULT_*).health()Unauthenticated health (GET /v1/sys/health, answers 200 in every node state).Asynchronoushealth().booleanisClosed()Returns whetherclose()was called.kv()The default KV mount (VaultConfig.kvMount()) with auto-detected version.A KV mount with auto-detected version; the same instance is returned for the same mount.A KV version 1 mount (no detection).A KV version 2 mount (no detection).leases()Lease renew / revoke / lookup and automatic lease renewal.Returns the namespace sent asX-Vault-Namespace.ping()Authenticated round trip (GET /v1/auth/token/lookup-self, allowed for every valid token).Asynchronousping().pki()The PKI engine on mountpki.The PKI engine on a mount.voidregister(AutoCloseable resource) Registers a resource (watcher, renewer, provider) closed with the client.Calls any Vault API path (/v1/<path>) with the client token, namespace, retries and error mapping.requestAsync(String method, String path, Object body) Asynchronousrequest(String, String, Object).secrets()SecretsProviderover the default KV mount.secrets(SecretsOptions options) SecretsProviderover a KV mount and base path.Returns the server version fromsys/health(e.g.AsynchronousserverVersion().voidReplaces the client token.voidReplaces the client token.sys()System backend (health, seal status, policies, mounts, auth methods, AppRole admin).token()Returns the current client token (from the config, a login orsetToken(codes.grow.packages.vault.core.Secret)).toString()transit()The transit engine on mounttransit.The transit engine on a mount.Returns the HTTP transport, for modules built on this client.withNamespace(String ns) Returns a view of this client whose requests carryX-Vault-Namespace: <ns>(""= the root namespace, no header; surrounding slashes are removed).wrapping()Response wrapping.
-
Method Details
-
create
Creates a client.- Parameters:
config- validated configuration- Returns:
- a new client
- Throws:
ConfigException- when TLS or proxy settings are invalid
-
fromEnv
Creates a client from the SDK and vendor environment variables (GROW_HASHICORP_VAULT_*thenVAULT_*).- Returns:
- a new client
-
builder
Starts a client builder.- Returns:
- a new builder
-
config
Returns the configuration.- Returns:
- the configuration
-
transport
Returns the HTTP transport, for modules built on this client.- Returns:
- the transport
-
token
Returns the current client token (from the config, a login orsetToken(codes.grow.packages.vault.core.Secret)).- Returns:
- the token, or empty
-
setToken
Replaces the client token.- Parameters:
token- the new token, or null to send none
-
setToken
Replaces the client token.- Parameters:
token- the new token, or null to send none
-
register
Registers a resource (watcher, renewer, provider) closed with the client.- Parameters:
resource- the resource
-
namespace
Returns the namespace sent asX-Vault-Namespace.- Returns:
- the namespace, or empty for the root namespace
-
withNamespace
Returns a view of this client whose requests carryX-Vault-Namespace: <ns>(""= the root namespace, no header; surrounding slashes are removed). The view shares the connection pool and starts with this client's current token; logins, token changes, KV version detection, renewers and watchers of the view do not affect this client, which stays unchanged. Closing the view stops its own renewers, leases and watchers; closing this client also closes every view.Vault Enterprise only. Vault OSS silently ignores the header and serves the root namespace, so on OSS a view reads and writes the root namespace and a wrong namespace is not detected.
VaultClient team = client.withNamespace("team-a"); team.kv().read("app/db"); // X-Vault-Namespace: team-a- Parameters:
ns- namespace path, e.g.team-aorteam-a/child- Returns:
- the view
- Throws:
ValidationException- whennsis null or this client is closedConfigException- whennscontains whitespace
-
auth
Logins, token self-service and token renewal.- Returns:
- the auth module
-
sys
System backend (health, seal status, policies, mounts, auth methods, AppRole admin).- Returns:
- the sys module
-
wrapping
Response wrapping.- Returns:
- the wrapping module
-
leases
Lease renew / revoke / lookup and automatic lease renewal.- Returns:
- the lease manager
-
kv
The default KV mount (VaultConfig.kvMount()) with auto-detected version.- Returns:
- the mount
-
kv
A KV mount with auto-detected version; the same instance is returned for the same mount.- Parameters:
mount- mount path- Returns:
- the mount
-
kvV1
A KV version 1 mount (no detection).- Parameters:
mount- mount path- Returns:
- the mount
-
kvV2
A KV version 2 mount (no detection).- Parameters:
mount- mount path- Returns:
- the mount
-
transit
The transit engine on mounttransit.- Returns:
- the transit module
-
transit
The transit engine on a mount.- Parameters:
mount- mount path- Returns:
- the transit module
-
database
The database engine on mountdatabase.- Returns:
- the database module
-
database
The database engine on a mount.- Parameters:
mount- mount path- Returns:
- the database module
-
pki
The PKI engine on mountpki.- Returns:
- the PKI module
-
pki
The PKI engine on a mount.- Parameters:
mount- mount path- Returns:
- the PKI module
-
secrets
SecretsProviderover the default KV mount.close()stops its watchers.- Returns:
- the provider
-
secrets
SecretsProviderover a KV mount and base path.- Parameters:
options- mount, base path, value field- Returns:
- the provider
-
request
Calls any Vault API path (/v1/<path>) with the client token, namespace, retries and error mapping. Use it for endpoints this SDK has no method for.- Parameters:
method- HTTP method (GET,POST,PUT,DELETE,LISTis sent asGET ?list=true)path- path below/v1/(each segment is percent-encoded)body- JSON body, may be null- Returns:
- the decoded envelope
-
requestAsync
Asynchronousrequest(String, String, Object).- Parameters:
method- HTTP methodpath- path below/v1/body- JSON body, may be null- Returns:
- a future with the decoded envelope
-
health
Unauthenticated health (GET /v1/sys/health, answers 200 in every node state).healthyis true only for an active, unsealed node;statusisactive,standby,perfstandby,sealedoruninitialized(unreachableon errors). Never throws except for cancellation and configuration errors.- Returns:
- the health status
- Throws:
CancelledException- when interrupted or closed
-
healthAsync
Asynchronoushealth().- Returns:
- a future with the health status
-
ping
Authenticated round trip (GET /v1/auth/token/lookup-self, allowed for every valid token).- Returns:
- the latency
- Throws:
AuthenticationException- on a missing, invalid or revoked token
-
pingAsync
Asynchronousping().- Returns:
- a future with the latency
-
serverVersion
Returns the server version fromsys/health(e.g.2.2.2).- Returns:
- the version string
- Throws:
UnsupportedException- when the server reports none
-
serverVersionAsync
AsynchronousserverVersion().- Returns:
- a future with the version
-
isClosed
public boolean isClosed()Returns whetherclose()was called.- Returns:
- true once closed
-
close
public void close()Stops token renewers, managed leases (revoking those withrevokeOnStop) and secret watchers, then releases the transport. Idempotent.- Specified by:
closein interfaceAutoCloseable
-
toString
-