config-vault

config-vault is a BSB config plugin that loads runtime config from Vault.

Only one BSB config plugin can be active. If BSB_CONFIG_PLUGIN=config-vault, Vault owns the full runtime config source.

Host language and plugin implementations

Choose the runtime language on each deployment profile. An application can have Node, C# and Python deployment profiles at the same time. Existing profiles default to nodejs; use csharp for .NET. A profile's language is locked once it has published versions, so create another profile when changing the runtime.

Catalog imports, private plugin uploads and publishing keys include the implementation language. The same plugin/version can be published separately for each language. Rotating a C# publishing credential does not rotate its Node counterpart. The plugin picker only offers native implementations for the selected deployment profile. Enabled plugins must match the host; disabled service references can describe a remote implementation.

Runtime responses include the profile language. Native hosts validate it before loading plugins or using a cached response. Generated clients can consume another language's service contract; choose its source language when installing the client rather than duplicating the shared service.

Runtime Behavior

config-vault is activated as the BSB config source with environment variables, not as a normal plugin config block in sec-config.yaml.

BSB_CONFIG_PLUGIN=config-vault
BSB_CONFIG_PLUGIN_PACKAGE=@bsb/config-vault
vaultUrl=https://vault.example.com
apiKeyId=vk_xxx
apiSecret=vs_xxx
timeoutMs=5000
staleAllowedHours=24
# cacheDir=/mounted/config-vault

The lower camel case keys are intentional. BSB reads config plugin env vars from the plugin schema, so these are the exact schema keys. staleAllowedHours defaults to 24 hours; set it to 0 to disable cached startup.

The API key is bound in Vault to:

• application,
• service group,
• deployment profile,
• optional container name,
• allowed config plugin id.

The container cannot ask for another profile. Vault derives the target from the API key and returns the latest active published version.

Runtime Overrides

A plugin must declare every field that may be overridden in its type-checked createConfigSchema metadata:

export const Config = createConfigSchema(
  schema,
  { envOverridePaths: ['database.instance', 'database.name'] },
);

An administrator must also enable environment overrides for that plugin in the deployment profile. The control is unavailable when the selected plugin version declares no overrideable paths.

PVE infrastructure can then inject one Secret Manager-backed JSON value:

BSB_CONFIG_OVERRIDES='{"services":{"core":{"database":{"instance":"project:region:instance","name":"preview-core-123"}}}}'

The top-level sections are services, events, and observable; their keys are the configured plugin aliases. Objects merge recursively, while arrays and scalar values replace the published value. Unknown plugins, sections, and undeclared paths fail startup. Overrides are applied in memory after loading Vault config, are validated by the normal plugin schemas, and are never sent to Vault or written to the last-known-good cache.

Failures

At startup, the client retries network errors, timeouts, HTTP 429, and HTTP 502/503/504 responses for up to 15 seconds. After any successful fetch it writes an AES-256-GCM encrypted last-known-good response under cacheDir, defaulting to .bsb/config-vault in the service working directory. The directory is created when needed. The cache key is derived from the runtime secret and is bound to the Vault origin and key id. Point cacheDir at persistent storage if the fallback must survive container replacement.

If the retry window expires, a cache no older than staleAllowedHours is loaded and a warning names its version and fetch time. Authentication/authorization failures, redirects, non-transient server errors, malformed responses, expired/tampered caches, and configs without an enabled service always fail closed. There is no fallback to config-env or config-default.

Startup therefore fails if:

• Vault is unreachable and no valid last-known-good cache exists,
• authentication fails,
• vaultUrl is not HTTPS and allowInsecureHttp is not enabled,
• no active version exists,
• Vault returns invalid config,
• the selected profile has no enabled service plugins.