Skip to content

feat(credentials): make the Vault credential driver an optional build feature #5709

Open

Description

@laik

User Story

I operate OpenShell gateways on Kubernetes and build gateway images from source for my deployments. Following the optional-integrations direction in #4723, I need a supported build selection that excludes the Vault credential-storage integration my deployment does not use, while keeping the default encrypted database credential store and the rest of the gateway functional. This issue covers the Vault portion of #4723 as a separately closable unit; the Kubernetes and AWS STS portions remain tracked there.

Problem Statement

openshell-credential-issuer depends on openshell-driver-vault unconditionally, and openshell-server / openshell-gateway inherit it. Selective gateway builds (--no-default-features --features compute-driver-docker,telemetry) remove compute drivers but still compile the Vault driver into every gateway. There is no supported way to omit Vault credential storage at build time, and no defined behavior for a gateway configured with credential_drivers = ["vault"] when the integration is absent.

Impact / Why This Matters

Downstream packaging (e.g., Nix, minimal Docker-only gateways) must carry patches to remove the Vault dependency, or ship code they cannot configure. Runtime configuration alone leaves the integration inactive but cannot remove its compile dependencies. Without a defined unsupported-build error, an omitted integration would fail confusingly at credential resolution time rather than clearly at startup.

Proposed Design

  • A default-on credential-driver-vault Cargo feature on openshell-credential-issuer, forwarded by openshell-server and openshell-gateway, following the existing compute-driver-* pattern.
  • A gateway built without the feature has no openshell-driver-vault in its normal/build dependency graph and rejects credential_drivers = ["vault"] (and in-tree vault driver tables) at startup with an error naming the feature and the transport = "uds" escape hatch.
  • The default encrypted database store, kubernetes-secrets, and the driver-agnostic UDS transport are unaffected; an external Vault driver process over UDS remains usable in an omitted build.
  • Default builds and the defaults-without-telemetry alias retain Vault support.
  • CI asserts the dependency boundary in both build modes and runs omitted-build tests; docs explain the selection.

Suggested UX

# Docker-only gateway without Vault credential storage.
cargo build --release -p openshell-gateway \
  --no-default-features --features compute-driver-docker,telemetry

Configuring credential_drivers = ["vault"] on that binary fails at startup with:
credential driver 'vault' is not included in this build; rebuild with the 'credential-driver-vault' feature or configure an external Vault driver with transport = 'uds'.

Acceptance Criteria

  • cargo tree -p openshell-gateway --no-default-features --features compute-driver-docker,telemetry --edges normal,build contains no openshell-driver-vault; the default graph does.
  • Vault can be omitted independently of telemetry and compute-driver features.
  • Omitted builds reject in-tree vault configuration at startup with a clear unsupported-build error; UDS vault configuration still parses and connects.
  • Default builds retain existing Vault functionality (unit + e2e).
  • defaults-without-telemetry stays in sync with default minus telemetry.
  • CI checks the omitted build boundary and tests; docs describe the feature.

Alternatives Considered

Agent Investigation

At dc236df1 (main): openshell-credential-issuer/Cargo.toml depends on openshell-driver-vault unconditionally; embedded/driver_config.rs registers BuiltinCredentialDriverKind::Vault and builds it in build_in_tree_driver; the UDS transport (embedded/transport.rs) is name-agnostic. A prototype implementation with omitted-build tests, a rust:verify:credential-driver-vault task, a branch-checks step, and docs exists on a fork branch and can be submitted as a PR once this issue is accepted. The Vault e2e lane (e2e:kubernetes:credential-drivers, vault backend) passes against a gateway built from that branch on a kind cluster with the OpenBao dev-TLS fixture.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:triage-neededOpened without agent diagnostics and needs triage

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions