Repository navigation
Description
User Story
I use OpenShell's Vault credential driver (openshell-driver-vault) against an enterprise Vault deployment that routes API requests through an additional line-of-business path prefix. I directly encountered the driver being unable to reach this deployment, so that OpenShell can store and resolve credentials in our enterprise Vault.
Problem Statement
The Vault credential driver builds every API URL through a single shared function that hardcodes the v1/ prefix:
// crates/openshell-driver-vault/src/lib.rs
fn url_for_path(&self, path: &str) -> Result<Url, Status> {
self.settings
.address
.join(&format!("v1/{path}"))
...
}Some enterprise Vault deployments require an extra routing segment immediately after /v1/:
/v1/<lob>/auth/<kubernetes-auth-mount>/login
/v1/<lob>/<kv-mount>/data/<secret-path>
There is no configuration field for this prefix today. Putting it into address does not work: URL joining produces incorrect path ordering or a duplicated /v1/ segment. This limitation was verified in v0.1.7–v0.1.9, v0.1.10-pre.3, and the inspected main revision.
Impact / Why This Matters
Users on enterprise Vault deployments with path-prefix routing cannot use the Vault credential driver at all — both Kubernetes auth login and every KV operation fail. The available workarounds are insufficient:
- Embedding the prefix in
addressbreaks URL construction (wrong ordering / duplicate/v1/). - Fronting Vault with a path-rewriting reverse proxy adds an extra network hop and operational component, and sits awkwardly with the driver's deliberate no-proxy / no-redirect / certificate-verification posture.
This is an adoption blocker for enterprises whose Vault platform teams mandate the prefix.
Proposed Design
Add an optional path-prefix field to the Vault credential driver configuration. When set, the driver inserts it immediately after /v1/ in every API URL, applied consistently through the shared URL-building function:
| Configuration | Generated API path |
|---|---|
| prefix omitted | /v1/{path} |
prefix = business-unit |
/v1/business-unit/{path} |
Scope of the prefix:
- Kubernetes authentication login;
- KV reads and writes (v1 and v2);
- KV metadata deletion;
- any future token renewal or revocation requests;
token_fileauthentication: KV operations also use the prefix.
The prefix must not be added to logical secret paths or persisted credential handles, so stored handles remain resolvable across restarts with the same configuration.
Validation and compatibility:
- Behavior is unchanged when the field is omitted.
- Empty values and unsafe path segments (e.g.
.., embedded/, query/fragment characters) are rejected at configuration validation time. - Existing HTTPS enforcement, certificate verification, no-proxy, and no-redirect protections are preserved.
- The field is configurable through the supported Helm gateway configuration interface.
Naming (open question): lob matches the enterprise terminology but is deployment-specific; api_path_prefix is more general and describes the mechanism. Either name satisfies the use case — maintainer preference welcome. This request concerns URL path-prefix routing only, not implicit support for the X-Vault-Namespace header.
Suggested UX (if applicable)
[openshell.credential_drivers.vault]
address = "https://vault.example.com:8200"
api_path_prefix = "business-unit" # or `lob = "business-unit"` — naming TBD
auth_method = "kubernetes"
kubernetes_auth_mount = "kubernetes"
role = "openshell-gateway"
service_account_token_path = "/var/run/secrets/kubernetes.io/serviceaccount/token"
mount = "secret"
kv_version = "2"With this configuration the driver issues:
POST https://vault.example.com:8200/v1/business-unit/auth/kubernetes/login
GET https://vault.example.com:8200/v1/business-unit/secret/data/<secret-path>
Acceptance Criteria
- Existing URLs remain unchanged when the prefix field is omitted.
- Configuring the prefix inserts it immediately after
/v1/for all driver API requests. - Tests cover Kubernetes and
token_fileauthentication, plus KV v1 and v2 reads/writes and metadata deletion. - Invalid prefix values (empty, unsafe path segments) fail configuration validation.
- Stored credential handles remain resolvable after restarting with the same configuration.
- The field is settable through the Helm gateway configuration interface, with the configuration docs updated.
Alternatives Considered
- Prefix inside
address: fails —Url::joinsemantics produce wrong path ordering or duplicate/v1/; also conflates the server origin with a routing concern. - Path-rewriting reverse proxy in front of Vault: works around the limitation but adds an extra hop, another component to operate and secure, and undermines the driver's intentional no-proxy/no-redirect design.
X-Vault-Namespaceheader support: a different mechanism (Vault Enterprise namespaces). It does not satisfy deployments that route by URL path prefix, and is out of scope for this request.- Gateway interceptors / supervisor middleware: these operate at the gRPC routing and sandbox egress boundaries, not on the credential driver's own Vault HTTP client, so they cannot rewrite these URLs.
A single optional driver configuration field applied in the shared URL builder is the smallest change that unblocks the use case without new infrastructure.
Agent Investigation
Verified on the current main checkout:
crates/openshell-driver-vault/src/lib.rs:474-479—url_for_pathhardcodesaddress.join(&format!("v1/{path}")).- All four request sites route through it: Kubernetes login (
lib.rs:355), KV read (lib.rs:394), KV write (lib.rs:427), KV metadata delete (lib.rs:454). A prefix applied in this one function covers every current API call. - Settings parsing rejects unknown fields (
settings_reject_unknown_fieldstest), so today there is no way to pass a prefix through configuration.
Activity
johntmyers commentedon Nov 20, 2026
Path prefix is fine I think.
laik commentedon Nov 20, 2026
TaylorMutch commentedon Nov 20, 2026
@laik a PR would be great, thanks!