> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Storage
> Configure Bifrost storage backends in Helm - SQLite, PostgreSQL (embedded and external), per-store overrides, and S3/GCS object storage for logs
Bifrost persists two types of data - **config** (providers, virtual keys, governance rules) and **logs** (request/response records). Each has its own store, both defaulting to the top-level `storage.mode`.
| Parameter | Description | Default |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `storage.mode` | Default backend for both stores (`sqlite` or `postgres`) | `sqlite` |
| `storage.configStore.type` | Override backend for the config store | `""` (inherits `storage.mode`) |
| `storage.logsStore.type` | Override backend for the logs store | `""` (inherits `storage.mode`) |
| `storage.logsStore.hiddenRequestTypes` | Request types hidden from dashboard and log API reads; logs are still stored. Rendered as `client.hidden_request_types`. Also editable in the UI under **Logs Settings**. See [Hiding request types from the dashboard](/architecture/framework/log-store#hiding-request-types-from-the-dashboard). | `[]` |
**ClickHouse is a logs-store-only backend.** The config store supports only `sqlite` and `postgres`. To use ClickHouse for logs, set `storage.logsStore.type: clickhouse` and keep the config store on SQLite or PostgreSQL — see [ClickHouse Logs Store](#clickhouse-logs-store) below.
When any store uses SQLite the chart deploys a **StatefulSet** with a PVC. With PostgreSQL only (no SQLite) it deploys a **Deployment**. Mixing backends (e.g. config=postgres, logs=sqlite) still requires a StatefulSet.
***
## SQLite (Default)
Simplest setup - no external database required. Bifrost runs as a StatefulSet with a persistent volume for the SQLite files.
| Parameter | Description | Default |
| ----------------------------------- | ----------------------------------------------- | --------------- |
| `storage.persistence.enabled` | Create a PVC for SQLite data | `true` |
| `storage.persistence.size` | PVC size | `10Gi` |
| `storage.persistence.accessMode` | PVC access mode | `ReadWriteOnce` |
| `storage.persistence.storageClass` | Storage class (leave empty for cluster default) | `""` |
| `storage.persistence.existingClaim` | Reuse an existing PVC | `""` |
```yaml theme={null}
# sqlite-values.yaml
image:
tag: "v1.4.11"
storage:
mode: sqlite
persistence:
enabled: true
size: 20Gi
# storageClass: "gp3" # uncomment to pin storage class
bifrost:
encryptionKey: "your-32-byte-encryption-key-here"
```
```bash theme={null}
helm install bifrost bifrost/bifrost -f sqlite-values.yaml
```
**Reuse an existing PVC** (e.g. after a StatefulSet migration):
```yaml theme={null}
storage:
persistence:
existingClaim: "bifrost-data"
```
Upgrading from SQLite to PostgreSQL requires a data migration - the two stores are not compatible. Plan accordingly before switching `storage.mode` on a running deployment.
### StatefulSet Migration (chart v2.0.0+)
Prior to v2.0.0, SQLite used a Deployment + manual PVC. v2.0.0 moved SQLite to a StatefulSet. If upgrading from an older chart:
```bash theme={null}
# 1. Scale down the old deployment
kubectl scale deployment bifrost --replicas=0
# 2. Note the existing PVC name
kubectl get pvc
# 3. Upgrade the chart, pointing at the existing claim
helm upgrade bifrost bifrost/bifrost \
--reuse-values \
--set storage.persistence.existingClaim= \
--set image.tag=v1.4.11
```
***
## Embedded PostgreSQL
The chart can deploy a PostgreSQL instance alongside Bifrost. Good for simple production setups where you don't have an existing database.
| Parameter | Description | Default |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `storage.mode` | Set to `postgres` | `sqlite` |
| `postgresql.enabled` | Deploy PostgreSQL as a sub-deployment | `false` |
| `postgresql.auth.username` | Database user | `bifrost` |
| `postgresql.auth.password` | Database password (ignored when `existingSecret` is set) | `bifrost_password` |
| `postgresql.auth.database` | Database name | `bifrost` |
| `postgresql.auth.existingSecret` | Name of an existing Kubernetes secret containing the password. When set, the chart skips creating its own secret — both the postgres pod and the Bifrost pod read from this secret. | `""` |
| `postgresql.auth.passwordKey` | Key inside `existingSecret` that holds the password | `"password"` |
| `postgresql.primary.persistence.size` | PVC size for PostgreSQL data | `8Gi` |
Ensure the database is created with **UTF8 encoding**. The embedded PostgreSQL deployment handles this automatically. See [PostgreSQL UTF8 Requirement](/quickstart/gateway/setting-up#postgresql-utf8-requirement) for manual setups.
```yaml theme={null}
# embedded-postgres-values.yaml
image:
tag: "v1.4.11"
storage:
mode: postgres
postgresql:
enabled: true
auth:
username: bifrost
password: "your-secure-postgres-password"
database: bifrost
primary:
persistence:
enabled: true
size: 50Gi
resources:
requests:
cpu: 500m
memory: 1Gi
limits:
cpu: 2000m
memory: 4Gi
bifrost:
encryptionKey: "your-32-byte-encryption-key-here"
```
```bash theme={null}
helm install bifrost bifrost/bifrost -f embedded-postgres-values.yaml
```
**Using an existing secret (Vault, ESO, Sealed Secrets)**
If you manage secrets externally, set `existingSecret` instead of providing a plaintext password. The chart will not create its own secret — both the postgres pod (`POSTGRES_PASSWORD`) and the Bifrost pod (`BIFROST_POSTGRES_PASSWORD`) mount the password directly from your secret.
```bash theme={null}
# Example: create the secret manually (VSO / ESO would do this automatically)
kubectl create secret generic postgres-credentials \
--from-literal=password='your-secure-postgres-password'
```
```yaml theme={null}
postgresql:
enabled: true
auth:
username: bifrost
database: bifrost
existingSecret: "postgres-credentials" # your secret name
passwordKey: "password" # key inside the secret
```
**Verify the connection from Bifrost:**
```bash theme={null}
kubectl exec -it deployment/bifrost -- nc -zv bifrost-postgresql 5432
```
***
## External PostgreSQL
Point Bifrost at an existing PostgreSQL instance - RDS, Cloud SQL, Azure Database, or self-managed.
| Parameter | Description | Default |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `postgresql.enabled` | Must be `false` | `false` |
| `postgresql.external.enabled` | Enable external connection | `false` |
| `postgresql.external.host` | Hostname or IP | `""` |
| `postgresql.external.port` | Port | `5432` |
| `postgresql.external.user` | Username | `bifrost` |
| `postgresql.external.database` | Database name | `bifrost` |
| `postgresql.external.sslMode` | SSL mode (`disable`, `require`, `verify-ca`, `verify-full`) | `disable` |
| `postgresql.external.existingSecret` | Secret name for the password. Mutually exclusive with `passwordCommand`. | `""` |
| `postgresql.external.passwordKey` | Key within the secret | `"password"` |
| `postgresql.external.passwordCommand` | Command executed by Bifrost to produce the database password on stdout for each new physical connection. Mutually exclusive with `existingSecret`; set only the executable path or name in `command` and pass arguments through `args`. | unset |
| `postgresql.external.connMaxLifetime` | Maximum lifetime for physical database connections, such as `"10m"` | unset |
```bash theme={null}
kubectl create secret generic external-postgres-credentials \
--from-literal=password='your-external-postgres-password'
```
```yaml theme={null}
# external-postgres-values.yaml
image:
tag: "v1.4.11"
storage:
mode: postgres
postgresql:
enabled: false
external:
enabled: true
host: "your-rds-endpoint.us-east-1.rds.amazonaws.com"
port: 5432
user: bifrost
database: bifrost
sslMode: require
existingSecret: "external-postgres-credentials"
passwordKey: "password"
bifrost:
encryptionKey: "your-32-byte-encryption-key-here"
```
```bash theme={null}
helm install bifrost bifrost/bifrost -f external-postgres-values.yaml
```
For dynamic credentials such as AWS RDS IAM auth tokens, use `passwordCommand` instead of `existingSecret`:
```yaml theme={null}
postgresql:
enabled: false
external:
enabled: true
host: "your-rds-endpoint.us-east-1.rds.amazonaws.com"
port: 5432
user: bifrost
database: bifrost
sslMode: require
passwordCommand:
command: aws
args:
- rds
- generate-db-auth-token
- --hostname
- your-rds-endpoint.us-east-1.rds.amazonaws.com
- --port
- "5432"
- --region
- us-east-1
- --username
- bifrost
timeout: 10s
connMaxLifetime: 10m
```
**Test connectivity before installing:**
```bash theme={null}
kubectl run pg-test --image=postgres:16-alpine --rm -it --restart=Never -- \
psql "host=your-rds-endpoint.us-east-1.rds.amazonaws.com dbname=bifrost user=bifrost sslmode=require" \
-c "SELECT version();"
```
***
## Separate PostgreSQL for Logs
By default the chart points both stores at the same PostgreSQL connection. Set `storage.logsStore.postgres.enabled: true` to give the logs store its own external PostgreSQL instance while the config store keeps using the top-level `postgresql` connection.
Use this when config and logs have different scaling or cost profiles: a small highly-available database for configuration, and a separate instance sized for log write throughput so log traffic never competes with config reads.
This applies only when the logs store resolves to `postgres`. When `storage.logsStore.postgres.enabled` is `false` (the default), every logs-store connection setting falls back to the shared `postgresql` connection and behavior is unchanged. The whole `postgres` block is absent from the shipped `values.yaml`, so when you enable it, set each field you need explicitly. There are no per-field defaults apart from `passwordKey`.
| Parameter | Description | Default |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------ |
| `storage.logsStore.postgres.enabled` | Point the logs store at a separate PostgreSQL instance | `false` |
| `storage.logsStore.postgres.host` | Hostname or IP of the logs database. Required when `enabled` is `true`. | unset |
| `storage.logsStore.postgres.port` | Port. Integer, or an `env.VAR_NAME` string. | unset |
| `storage.logsStore.postgres.user` | Username | unset |
| `storage.logsStore.postgres.database` | Database name | unset |
| `storage.logsStore.postgres.sslMode` | `disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full` | unset |
| `storage.logsStore.postgres.password` | Plaintext password. Prefer `existingSecret`. | unset |
| `storage.logsStore.postgres.existingSecret` | Secret holding the password. Takes precedence over `password`, and is mounted as `BIFROST_LOGS_POSTGRES_PASSWORD`. | unset |
| `storage.logsStore.postgres.passwordKey` | Key within the secret | `"password"` |
| `storage.logsStore.postgres.passwordCommand` | Command executed by Bifrost to produce the password on stdout, for dynamic credentials such as RDS IAM auth | unset |
| `storage.logsStore.postgres.connMaxLifetime` | Maximum lifetime for physical connections, such as `"10m"` | unset |
```bash theme={null}
kubectl create secret generic postgres-credentials \
--from-literal=password='your-config-db-password'
kubectl create secret generic logs-postgres-credentials \
--from-literal=password='your-logs-db-password'
```
```yaml theme={null}
# split-postgres-values.yaml
image:
tag: "v1.4.11"
storage:
mode: postgres
logsStore:
type: postgres
maxIdleConns: 10
maxOpenConns: 200
postgres:
enabled: true
host: "logs-db.example.com"
port: 5432
user: bifrost
database: bifrost_logs
sslMode: require
existingSecret: "logs-postgres-credentials"
passwordKey: "password"
# config store keeps using this connection
postgresql:
enabled: false
external:
enabled: true
host: "config-db.example.com"
port: 5432
user: bifrost
database: bifrost_config
sslMode: require
existingSecret: "postgres-credentials"
passwordKey: "password"
bifrost:
encryptionKey: "your-32-byte-encryption-key-here"
```
```bash theme={null}
helm install bifrost bifrost/bifrost -f split-postgres-values.yaml
```
For dynamic credentials on the logs database, use `passwordCommand` instead of `existingSecret`:
```yaml theme={null}
storage:
logsStore:
postgres:
enabled: true
host: "logs-db.example.com"
port: 5432
user: bifrost
database: bifrost_logs
sslMode: require
passwordCommand:
command: aws
args:
- rds
- generate-db-auth-token
- --hostname
- logs-db.example.com
- --port
- "5432"
- --region
- us-east-1
- --username
- bifrost
timeout: 10s
connMaxLifetime: 10m
```
***
## Mixed Backend (Config = Postgres, Logs = SQLite)
Run the config store on PostgreSQL (fast lookups, shared across replicas) while keeping logs on SQLite (simpler, cheaper for append-heavy workloads).
```yaml theme={null}
# mixed-values.yaml
image:
tag: "v1.4.11"
storage:
mode: sqlite # default fallback
configStore:
type: postgres # override: config uses postgres
logsStore:
type: sqlite # explicit: logs use sqlite
persistence:
enabled: true
size: 20Gi # for the SQLite logs store
postgresql:
external:
enabled: true
host: "your-postgres-host.example.com"
port: 5432
user: bifrost
database: bifrost
sslMode: require
existingSecret: "postgres-credentials"
passwordKey: "password"
bifrost:
encryptionKey: "your-32-byte-encryption-key-here"
```
```bash theme={null}
kubectl create secret generic postgres-credentials \
--from-literal=password='your-postgres-password'
helm install bifrost bifrost/bifrost -f mixed-values.yaml
```
In mixed mode, Bifrost deploys a StatefulSet (because SQLite is in use) with both a PostgreSQL connection and a local PVC for the SQLite log store.
**PostgreSQL connection pool tuning** (high log volume):
```yaml theme={null}
storage:
configStore:
type: postgres
maxIdleConns: 5
maxOpenConns: 50
logsStore:
type: postgres
maxIdleConns: 10
maxOpenConns: 100
```
***
## ClickHouse Logs Store
ClickHouse is a column-oriented backend for the **logs store**, built for high-volume log ingestion and fast analytical queries at scale. Set `storage.logsStore.type: clickhouse` and provide a `storage.logsStore.clickhouse` block. The config store stays on SQLite or PostgreSQL.
ClickHouse applies to the logs store only. `storage.configStore.type` must remain `sqlite` or `postgres`. The chart does **not** deploy ClickHouse for you — point Bifrost at an existing ClickHouse instance (self-managed or ClickHouse Cloud).
```bash theme={null}
kubectl create secret generic postgres-credentials \
--from-literal=password='your-postgres-password'
kubectl create secret generic clickhouse-credentials \
--from-literal=password='your-clickhouse-password'
```
```yaml theme={null}
# clickhouse-logs-values.yaml
image:
tag: "v1.4.11"
storage:
mode: postgres # config store backend
configStore:
type: postgres # config store: sqlite or postgres only
logsStore:
type: clickhouse
clickhouse:
host: "clickhouse.default.svc.cluster.local" # required
port: "9000" # native 9000 (9440 TLS); http 8123 (8443 TLS)
database: "bifrost"
username: "default"
password: "env.CLICKHOUSE_PASSWORD"
protocol: "native" # native or http
secure: false # enable TLS
dialTimeout: 10000 # dial timeout in milliseconds
cluster: "" # optional; runs DDL ON CLUSTER with replicated engines
postgresql:
external:
enabled: true
host: "your-postgres-host.example.com"
port: 5432
user: bifrost
database: bifrost
sslMode: require
existingSecret: "postgres-credentials"
passwordKey: "password"
# inject the ClickHouse password as an env var referenced by password: "env.CLICKHOUSE_PASSWORD" above
env:
- name: CLICKHOUSE_PASSWORD
valueFrom:
secretKeyRef:
name: clickhouse-credentials
key: password
bifrost:
encryptionKey: "your-32-byte-encryption-key-here"
```
```bash theme={null}
helm install bifrost bifrost/bifrost -f clickhouse-logs-values.yaml
```
| Parameter | Description | Default |
| ------------------------------------------ | -------------------------------------------------------------------------------------------- | -------------- |
| `storage.logsStore.type` | Set to `clickhouse` | `""` |
| `storage.logsStore.clickhouse.host` | ClickHouse host (**required**) | - |
| `storage.logsStore.clickhouse.port` | Port as a string. Defaults by protocol: native `9000` (`9440` TLS), http `8123` (`8443` TLS) | protocol-based |
| `storage.logsStore.clickhouse.database` | Database name | `default` |
| `storage.logsStore.clickhouse.username` | ClickHouse user | - |
| `storage.logsStore.clickhouse.password` | ClickHouse password (supports `env.` prefix) | - |
| `storage.logsStore.clickhouse.protocol` | Wire protocol: `native` or `http` | `native` |
| `storage.logsStore.clickhouse.secure` | Enable TLS | `false` |
| `storage.logsStore.clickhouse.dialTimeout` | Connection dial timeout in milliseconds | `10000` |
| `storage.logsStore.clickhouse.cluster` | Optional cluster name; runs DDL `ON CLUSTER` with replicated engines | `""` |
With ClickHouse, the table **TTL** comes from `logs_store.retention_days`, which the chart does not expose yet. Set it in `config.json` directly if you need ClickHouse to expire rows on its own. Background log cleanup is controlled separately by `bifrost.client.logRetentionDays`. The PostgreSQL-only `matviewRefreshInterval` and `matviewRefreshTimeout` settings have no effect on ClickHouse.
***
## Object Storage for Logs
Offload large request/response payloads from the database to S3 or GCS. The DB retains only lightweight index records; payloads are fetched on demand.
### AWS S3
**Required IAM permissions**
The IAM user or role needs the following permissions on your bucket:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "BucketAccess",
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": "arn:aws:s3:::bifrost-logs"
},
{
"Sid": "ObjectAccess",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:PutObjectTagging",
"s3:GetObjectTagging"
],
"Resource": "arn:aws:s3:::bifrost-logs/*"
}
]
}
```
```bash theme={null}
kubectl create secret generic s3-credentials \
--from-literal=access-key-id='AKIAIOSFODNN7EXAMPLE' \
--from-literal=secret-access-key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
```
```yaml theme={null}
storage:
logsStore:
objectStorageExcludeFields:
- output_message
objectStorage:
enabled: true
type: s3
bucket: "bifrost-logs"
prefix: "bifrost"
compress: true # gzip compression
# S3 configuration
region: us-east-1
accessKeyId: "env.S3_ACCESS_KEY_ID"
secretAccessKey: "env.S3_SECRET_ACCESS_KEY"
# endpoint: "" # Custom endpoint for MinIO / Cloudflare R2
# forcePathStyle: false # Set true for MinIO
bifrost:
# inject S3 credentials as env vars
providerSecrets:
s3-access-key:
existingSecret: "s3-credentials"
key: "access-key-id"
envVar: "S3_ACCESS_KEY_ID"
s3-secret-key:
existingSecret: "s3-credentials"
key: "secret-access-key"
envVar: "S3_SECRET_ACCESS_KEY"
```
`storage.logsStore.objectStorageExcludeFields` keeps selected LLM log payload fields in Postgres while still offloading the rest to object storage. Use DB payload field names such as `output_message`, `input_history`, `raw_request`, or `raw_response`. MCP logs always offload the full tool log and keep dashboard/table fields plus a 200-character input preview in Postgres.
**Using IAM role (IRSA / instance profile) instead of static keys:**
```yaml theme={null}
storage:
logsStore:
objectStorage:
enabled: true
type: s3
bucket: "bifrost-logs"
region: us-east-1
# No accessKeyId / secretAccessKey - uses SDK default chain
roleArn: "arn:aws:iam::123456789012:role/BifrostS3Role"
```
### Google Cloud Storage
```bash theme={null}
kubectl create secret generic gcs-credentials \
--from-literal=service-account-json="$(cat service-account-key.json)"
```
```yaml theme={null}
storage:
logsStore:
objectStorage:
enabled: true
type: gcs
bucket: "bifrost-logs"
prefix: "bifrost"
compress: true
# GCS configuration
projectId: "my-gcp-project"
credentialsJson: "env.GCS_CREDENTIALS_JSON" # omit for Workload Identity
bifrost:
providerSecrets:
gcs-creds:
existingSecret: "gcs-credentials"
key: "service-account-json"
envVar: "GCS_CREDENTIALS_JSON"
```
### MinIO (Self-Hosted)
```yaml theme={null}
storage:
logsStore:
objectStorage:
enabled: true
type: s3
bucket: "bifrost-logs"
prefix: "bifrost"
compress: false
region: us-east-1 # can be any value for MinIO
endpoint: "http://minio.minio-ns.svc.cluster.local:9000"
accessKeyId: "env.MINIO_ACCESS_KEY"
secretAccessKey: "env.MINIO_SECRET_KEY"
forcePathStyle: true # required for MinIO
```
Apply any of the object storage options above with:
```bash theme={null}
helm upgrade bifrost bifrost/bifrost \
--reuse-values \
-f object-storage-values.yaml
```
***
## Vector Store
A vector store is required for [semantic caching](/deployment-guides/helm/plugins). Choose from Weaviate, Redis, or Qdrant (embedded or external), or Pinecone (external only).
### Weaviate
```yaml theme={null}
vectorStore:
enabled: true
type: weaviate
weaviate:
enabled: true # deploy embedded Weaviate
replicas: 1
persistence:
enabled: true
size: 20Gi
resources:
requests:
cpu: 500m
memory: 1Gi
limits:
cpu: 2000m
memory: 4Gi
```
**External Weaviate:**
```yaml theme={null}
vectorStore:
enabled: true
type: weaviate
weaviate:
enabled: false
external:
enabled: true
scheme: https
host: "weaviate.example.com"
apiKey: "env.WEAVIATE_API_KEY"
grpcHost: "weaviate-grpc.example.com"
grpcSecured: true
existingSecret: "weaviate-credentials"
apiKeyKey: "api-key"
```
### Redis / Valkey
```yaml theme={null}
vectorStore:
enabled: true
type: redis
redis:
enabled: true # deploy embedded Redis
auth:
enabled: true
password: "redis_password"
master:
persistence:
size: 8Gi
```
**External Redis / AWS MemoryDB:**
```bash theme={null}
kubectl create secret generic redis-credentials \
--from-literal=password='your-redis-password'
```
```yaml theme={null}
vectorStore:
enabled: true
type: redis
redis:
enabled: false
external:
enabled: true
host: "your-redis.cache.amazonaws.com"
port: 6379
useTls: true
clusterMode: true # required for AWS MemoryDB
existingSecret: "redis-credentials"
passwordKey: "password"
```
### Qdrant
```yaml theme={null}
vectorStore:
enabled: true
type: qdrant
qdrant:
enabled: true # deploy embedded Qdrant
persistence:
size: 10Gi
```
**External Qdrant:**
```bash theme={null}
kubectl create secret generic qdrant-credentials \
--from-literal=api-key='your-qdrant-api-key'
```
```yaml theme={null}
vectorStore:
enabled: true
type: qdrant
qdrant:
enabled: false
external:
enabled: true
host: "qdrant.example.com"
port: 6334
useTls: true
existingSecret: "qdrant-credentials"
apiKeyKey: "api-key"
```
### Pinecone
Pinecone is external-only.
```bash theme={null}
kubectl create secret generic pinecone-credentials \
--from-literal=api-key='your-pinecone-api-key'
```
```yaml theme={null}
vectorStore:
enabled: true
type: pinecone
pinecone:
external:
enabled: true
indexHost: "your-index.svc.us-east1-gcp.pinecone.io"
existingSecret: "pinecone-credentials"
apiKeyKey: "api-key"
```
Apply any of the vector store options above with:
```bash theme={null}
helm install bifrost bifrost/bifrost \
--set image.tag=v1.4.11 \
-f storage-values.yaml
```