Key Vault Secrets Reference
Define Azure Key Vault secret names and map them in global.remoteSecrets before your first Helm deploy.
This page lists Key Vault secret key names (chart defaults). These are configuration identifiers — not passwords or credentials. Store actual values only in Key Vault; never commit them to Git or Helm values files.
The chart maps Key Vault secret names to Kubernetes secret keys via External Secrets. Defaults live in values.yaml; per-environment overrides go in values-<env>.yaml (see sample values-release.yaml in the chart — placeholder hostnames and resource IDs only).
Flow
- Platform prerequisites — DB passwords and optional SSL material exist in Key Vault (your provisioning tool, console, or automation).
- One-time setup — run install scripts (
create-dbs-azure.sh, platform install script) to verify prerequisites and create application secrets. - SecretStore authenticates with Workload Identity.
- ExternalSecret per service syncs into K8s Secrets.
- Pods consume env vars or mounted files.
Platform prerequisites (verify only)
Install scripts check these with az keyvault secret show. Scripts may create missing application secrets but not infrastructure passwords.
| Key Vault secret | Required | Purpose |
|---|---|---|
azure-postgres-master-password or bh-dev-user-password | Yes | bh_dev_user (migrations / Alembic) — prefer bh-dev-user-password for cross-cloud parity |
bh-app-user-password | Yes | bh_app_user (runtime DML) |
bh-kcdbpwd | Yes | keycloak_db_user (KC_DB_PASSWORD on bhkeycloak) |
bh-postgres-ssl-cert | No | PostgreSQL server CA (PEM) |
Optional SSL secrets produce a warning only when missing — skip them if postgresSSLMode does not require client certificates.
One-time application secrets (script creates if missing)
| Key Vault secret | Purpose |
|---|---|
bh-kcadminpwd | Keycloak admin UI password |
bh-keycloak-grant-type | Grant type (default: password) |
bh-catalog-decryption-key | Catalog decryption key |
bh-temp-tenant-user-password | Temporary tenant password |
bh-rabbitmq-password | RabbitMQ password |
bh-redis-password | Redis password |
bh-langchain-api-key | LangChain API key |
bh-oauth-token | OAuth token (audit API) |
license-catalog | Catalog license string |
license-catalog-pub-key | Public key for license verification |
TLS edge secrets follow the pattern <env>-<cloud>-bighammer-tls-{crt,key} (for example <env>-az-bighammer-tls-crt / <env>-az-bighammer-tls-key). They are normally created by cert-manager PushSecret — see TLS Options.
Application database dual-role
Services on the application database use two PostgreSQL roles, matching create-dbs-azure.sh grants:
| Env var | DB role | Key Vault secret | Used for |
|---|---|---|---|
POSTGRES_USER + POSTGRES_PASSWORD | bh_dev_user | bh-dev-user-password (preferred) or azure-postgres-master-password | Alembic / migrations — DDL |
BH_APP_USER + BH_APP_USER_PASSWORD | bh_app_user | bh-app-user-password | Runtime SQLAlchemy — DML only |
global:
remoteSecrets:
postgres:
password: bh-dev-user-password # POSTGRES_PASSWORD → bh_dev_user
app:
userPassword: bh-app-user-password # BH_APP_USER_PASSWORD → bh_app_user
Mismatch between Key Vault values and PostgreSQL user passwords is the most common cause of password authentication failed at pod startup.
Keycloak server database
The Keycloak server pod (bhkeycloak) is not on the application database:
| Resource | Reference name | Chart mapping |
|---|---|---|
| Database | keycloak_db_<env> | global.bhkeycloak.env.KC_DB_URL |
| User | keycloak_db_user | global.bhkeycloak.env.KC_DB_USERNAME |
| Password | bh-kcdbpwd | global.remoteSecrets.keycloak.dbPassword |
bhkeycloakapi uses the application database (schema keycloakapi_db), not the Keycloak server database.
Chart defaults (global.remoteSecrets)
| Values path | Default Key Vault name | K8s key |
|---|---|---|
postgres.password | bh-dev-user-password | POSTGRES_PASSWORD |
app.userPassword | bh-app-user-password | BH_APP_USER_PASSWORD |
keycloak.dbPassword | bh-kcdbpwd | KC_DB_PASSWORD |
keycloak.adminPassword | bh-kcadminpwd | KEYCLOAK_ADMIN_PASSWORD |
rabbitmq.password | bh-rabbitmq-password | RABBITMQ_PASSWORD |
tls.cert / tls.key | <env>-az-bighammer-tls-crt / <env>-az-bighammer-tls-key (example) | TLS PEM files |
Override any name in values-<env>.yaml when your Key Vault naming convention differs.
How secrets flow (detail)
- Platform engineer stores secrets in Azure Key Vault
- SecretStore (namespace-scoped) authenticates via Workload Identity
- ExternalSecret per service syncs keys into a Kubernetes Secret
- Pods mount or reference env vars from the synced secret
See External Secrets Operator and Architecture.
Auto-created by install scripts
These can be generated and pushed by create-dbs-azure.sh and the platform install script:
| Key Vault secret name | Kubernetes key(s) | Used by |
|---|---|---|
azure-postgres-master-password | POSTGRES_PASSWORD | APIs, workers, Keycloak (dev path) |
bh-kcadminpwd | KEYCLOAK_ADMIN_PASSWORD | Keycloak, Keycloak API |
bh-kcdbpwd | KC_DB_PASSWORD | Keycloak |
bh-app-user-password | BH_APP_USER_PASSWORD | APIs (when global.dev.enabled) |
bh-dev-user-password | (script reference) | Alternate dev DB user |
bh-temp-tenant-user-password | TEMPERORY_TENANT_USER_PASSWORD | Keycloak API (dev) |
bh-rabbitmq-password | RABBITMQ_PASSWORD | APIs, workers, AI agent |
bh-redis-password | REDIS_PASSWORD | AI agent |
bh-catalog-decryption-key | DECRYPTION_KEY | Catalog API, AI agent, Keycloak API |
azure-storage-account-name | azurestorageaccountname | Storage ExternalSecret, AI agent |
azure-storage-account-key | azurestorageaccountkey | Storage ExternalSecret, AI agent |
Customer-provided secrets
Provision these in Key Vault before deployment (or use install script placeholder mode for non-production):
| Key Vault secret name | Description |
|---|---|
bh-client-secret | Entra app client secret (Workload Identity / API Azure SDK) |
bh-github-token | GitHub PAT for schema repository access |
bh-aws-access-key | AWS access key (legacy integrations / optional) |
bh-aws-secret-access-key | AWS secret key (legacy integrations / optional) |
bh-oauth-token | OAuth token for audit/API integrations |
bh-langchain-api-key | LangChain / observability API key |
bh-postgres-ssl-cert | PostgreSQL server CA certificate (PEM) |
bh-keycloak-grant-type | Keycloak grant type (e.g. password) |
license-catalog | Catalog license file content |
license-catalog-pub-key | Public key for license verification |
<env>-az-bighammer-tls-crt | PEM TLS certificate (example; use <env>-az-bighammer-tls-crt) |
<env>-az-bighammer-tls-key | PEM TLS private key (example; use <env>-az-bighammer-tls-key) |
:::tip TLS secret naming
Ingress TLS uses a Kubernetes secret name from global.ingress.tlsSecretName (for example <env>-az-bighammer-tls). The Key Vault keys that feed application consumers are defined in global.remoteSecrets.tls and ExternalSecret templates.
:::
Per-service ExternalSecret mapping
| Sub-chart | Additional Key Vault keys (beyond shared DB password) |
|---|---|
| bhauditapi | bh-oauth-token, bh-aws-access-key, bh-aws-secret-access-key, bh-rabbitmq-password, bh-client-secret |
| bhcatalogapi | bh-catalog-decryption-key, bh-github-token, bh-rabbitmq-password, license-catalog, license-catalog-pub-key, bh-client-secret |
| bhaiagent | bh-langchain-api-key, bh-github-token, bh-redis-password, bh-catalog-decryption-key, storage keys |
| bhkeycloak | bh-kcadminpwd, bh-kcdbpwd, wildcard TLS crt/key |
| bhkeycloakapi | bh-keycloak-grant-type, bh-kcadminpwd, bh-catalog-decryption-key |
| bhui | Wildcard TLS crt/key (ingress TLS secret) |
| bhnginx | Wildcard TLS crt/key |
| Parent chart | azure-storage-account-name, azure-storage-account-key |
Workers (bhcatalogworker, bhauditworker, bhaiagentworker, bhcelerybeat) follow the same patterns as their corresponding APIs.
Creating secrets in Key Vault
az keyvault secret set \
--vault-name <YOUR_KEY_VAULT_NAME> \
--name <SECRET_NAME> \
--value "<SECRET_VALUE>"
For file-based secrets (TLS certificate):
az keyvault secret set \
--vault-name <YOUR_KEY_VAULT_NAME> \
--name <env>-az-bighammer-tls-crt \
--file /path/to/cert.pem
az keyvault secret set \
--vault-name <YOUR_KEY_VAULT_NAME> \
--name <env>-az-bighammer-tls-key \
--file /path/to/key.pem
RBAC requirements
| Principal | Role |
|---|---|
| ESO managed identity | Key Vault Secrets User on the vault |
| Install / bootstrap operator | Key Vault Secrets Officer (temporary, for initial upload) |
| Application managed identities | Key Vault Secrets User (if apps read vault directly) |
RBAC propagation can take 60–120 seconds after assignment.
Related
| Topic | Link |
|---|---|
| Bootstrap scripts | Scripts Reference |
| TLS naming | TLS Options |
| GCP equivalent | Secret Manager Secrets |
| External docs | Azure Key Vault secrets · ESO Azure provider |