Storage

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 (`sqlite` or `postgres`)	`""` (inherits `storage.mode`)
`storage.logsStore.type`	Override backend for the logs store (`sqlite`, `postgres`, or `clickhouse`)	`""` (inherits `storage.mode`)

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 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	`""`

# 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"

helm install bifrost bifrost/bifrost -f sqlite-values.yaml

Reuse an existing PVC (e.g. after a StatefulSet migration):

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:

# 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=<your-old-pvc-name> \
  --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 for manual setups.

# 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"

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.

# Example: create the secret manually (VSO / ESO would do this automatically)
kubectl create secret generic postgres-credentials \
  --from-literal=password='your-secure-postgres-password'

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:

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

kubectl create secret generic external-postgres-credentials \
  --from-literal=password='your-external-postgres-password'

# 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"

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:

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:

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

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'

# 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"

helm install bifrost bifrost/bifrost -f split-postgres-values.yaml

For dynamic credentials on the logs database, use passwordCommand instead of existingSecret:

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).

# 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"

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):

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).

kubectl create secret generic postgres-credentials \
  --from-literal=password='your-postgres-password'

kubectl create secret generic clickhouse-credentials \
  --from-literal=password='your-clickhouse-password'

# 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"

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:

{
  "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/*"
    }
  ]
}

kubectl create secret generic s3-credentials \
  --from-literal=access-key-id='AKIAIOSFODNN7EXAMPLE' \
  --from-literal=secret-access-key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'

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:

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

kubectl create secret generic gcs-credentials \
  --from-literal=service-account-json="$(cat service-account-key.json)"

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)

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:

helm upgrade bifrost bifrost/bifrost \
  --reuse-values \
  -f object-storage-values.yaml

Vector Store

A vector store is required for semantic caching. Choose from Weaviate, Redis, or Qdrant (embedded or external), or Pinecone (external only).

Weaviate

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:

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

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:

kubectl create secret generic redis-credentials \
  --from-literal=password='your-redis-password'

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

vectorStore:
  enabled: true
  type: qdrant
  qdrant:
    enabled: true          # deploy embedded Qdrant
    persistence:
      size: 10Gi

External Qdrant:

kubectl create secret generic qdrant-credentials \
  --from-literal=api-key='your-qdrant-api-key'

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.

kubectl create secret generic pinecone-credentials \
  --from-literal=api-key='your-pinecone-api-key'

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:

helm install bifrost bifrost/bifrost \
  --set image.tag=v1.4.11 \
  -f storage-values.yaml

Managed Kubernetes

Hosted Containers

Config as Code

Enterprise Deployment

Common setup instructions

SQLite (Default)

StatefulSet Migration (chart v2.0.0+)

Embedded PostgreSQL

External PostgreSQL

Separate PostgreSQL for Logs

Mixed Backend (Config = Postgres, Logs = SQLite)

ClickHouse Logs Store

Object Storage for Logs

AWS S3

Google Cloud Storage

MinIO (Self-Hosted)

Vector Store

Weaviate

Redis / Valkey

Qdrant

Pinecone

​SQLite (Default)

​StatefulSet Migration (chart v2.0.0+)

​Embedded PostgreSQL

​External PostgreSQL

​Separate PostgreSQL for Logs

​Mixed Backend (Config = Postgres, Logs = SQLite)

​ClickHouse Logs Store

​Object Storage for Logs

​AWS S3

​Google Cloud Storage

​MinIO (Self-Hosted)

​Vector Store

​Weaviate

​Redis / Valkey

​Qdrant

​Pinecone

SQLite (Default)

StatefulSet Migration (chart v2.0.0+)

Embedded PostgreSQL

External PostgreSQL

Separate PostgreSQL for Logs

Mixed Backend (Config = Postgres, Logs = SQLite)

ClickHouse Logs Store

Object Storage for Logs

AWS S3

Google Cloud Storage

MinIO (Self-Hosted)

Vector Store

Weaviate

Redis / Valkey

Qdrant

Pinecone