Helm

Deploy Bifrost on Kubernetes using the official Helm chart. This is the recommended way to deploy Bifrost on Kubernetes with production-ready defaults and flexible configuration.

Prerequisites

Kubernetes cluster (v1.19+)
kubectl configured
Helm 3.2.0+ installed
(Optional) Persistent Volume provisioner
(Optional) Ingress controller

Quick Start

Add Helm Repository

helm repo add bifrost https://maximhq.github.io/bifrost/helm-charts
helm repo update

Install Bifrost

helm install bifrost bifrost/bifrost --set image.tag=v1.3.37

The image.tag parameter is required. Check Docker Hub for available versions.

This deploys Bifrost with:

SQLite storage (10Gi PVC)
Single replica
ClusterIP service

Access Bifrost

kubectl port-forward svc/bifrost 8080:8080
curl http://localhost:8080/metrics

Deployment Patterns

Development
Production
AI Workloads
Multi-Provider
External Database
Kubernetes Secrets

Development Setup

Simple setup for local testing and development.

helm install bifrost bifrost/bifrost \
  --set image.tag=v1.3.37 \
  --set bifrost.providers.openai.keys[0].value="sk-your-key" \
  --set bifrost.providers.openai.keys[0].weight=1

Features:

SQLite storage
Single replica
No auto-scaling
ClusterIP service

Access:

kubectl port-forward svc/bifrost 8080:8080

Configuration

Key Parameters

Parameter	Description	Default
`image.tag`	Required. Bifrost image version (e.g., v1.3.37)	`""`
`replicaCount`	Number of replicas	`1`
`storage.mode`	Storage backend (sqlite/postgres)	`sqlite`
`storage.persistence.size`	PVC size for SQLite	`10Gi`
`postgresql.enabled`	Deploy PostgreSQL	`false`
`vectorStore.enabled`	Enable vector store	`false`
`vectorStore.type`	Vector store type (weaviate/redis/qdrant)	`none`
`bifrost.encryptionKey`	Encryption key	`""`
`ingress.enabled`	Enable ingress	`false`
`autoscaling.enabled`	Enable HPA	`false`

Secret Reference Parameters

Use existing Kubernetes secrets instead of plain-text values:

Parameter	Description	Default
`bifrost.encryptionKeySecret.name`	Secret name for encryption key	`""`
`bifrost.encryptionKeySecret.key`	Key within the secret	`""`
`postgresql.external.existingSecret`	Secret name for PostgreSQL password	`""`
`postgresql.external.passwordKey`	Key within the secret	`"password"`
`vectorStore.redis.external.existingSecret`	Secret name for Redis password	`""`
`vectorStore.redis.external.passwordKey`	Key within the secret	`"password"`
`vectorStore.weaviate.external.existingSecret`	Secret name for Weaviate API key	`""`
`vectorStore.weaviate.external.apiKeyKey`	Key within the secret	`"api-key"`
`vectorStore.qdrant.external.existingSecret`	Secret name for Qdrant API key	`""`
`vectorStore.qdrant.external.apiKeyKey`	Key within the secret	`"api-key"`
`bifrost.plugins.maxim.secretRef.name`	Secret name for Maxim API key	`""`
`bifrost.plugins.maxim.secretRef.key`	Key within the secret	`"api-key"`
`bifrost.providerSecrets.<provider>.existingSecret`	Secret name for provider API key	`""`
`bifrost.providerSecrets.<provider>.key`	Key within the secret	`"api-key"`
`bifrost.providerSecrets.<provider>.envVar`	Environment variable name to inject	`""`

Provider Configuration

Add provider keys via values file:

bifrost:
  providers:
    openai:
      keys:
        - value: "sk-..."
          weight: 1
    anthropic:
      keys:
        - value: "sk-ant-..."
          weight: 1

Or via command line:

helm install bifrost bifrost/bifrost \
  --set image.tag=v1.3.37 \
  --set bifrost.providers.openai.keys[0].value="sk-..." \
  --set bifrost.providers.openai.keys[0].weight=1

Using Environment Variables for Provider Keys

Bifrost supports env.VAR_NAME syntax to reference environment variables. Combined with providerSecrets, you can keep API keys in Kubernetes secrets:

bifrost:
  providers:
    openai:
      keys:
        - value: "env.OPENAI_API_KEY"  # References environment variable
          weight: 1
  
  # Inject secrets as environment variables
  providerSecrets:
    openai:
      existingSecret: "my-openai-secret"
      key: "api-key"
      envVar: "OPENAI_API_KEY"

This pattern:

Creates a Kubernetes secret with the API key
Injects the secret as an environment variable (OPENAI_API_KEY)
Bifrost resolves env.OPENAI_API_KEY at runtime

Plugin Configuration

Enable and configure plugins:

bifrost:
  plugins:
    telemetry:
      enabled: true
      config: {}
    
    logging:
      enabled: true
      config: {}
    
    governance:
      enabled: true
      config:
        is_vk_mandatory: false
    
    semanticCache:
      enabled: true
      config:
        provider: "openai"
        embedding_model: "text-embedding-3-small"
        dimension: 1536
        threshold: 0.8
        ttl: "5m"
        cache_by_model: true
        cache_by_provider: true

Operations

Upgrade

# Update repository
helm repo update

# Upgrade with same values
helm upgrade bifrost bifrost/bifrost --reuse-values

# Upgrade with new values
helm upgrade bifrost bifrost/bifrost -f your-values.yaml

Rollback

# View release history
helm history bifrost

# Rollback to previous version
helm rollback bifrost

# Rollback to specific revision
helm rollback bifrost 2

Uninstall

# Uninstall release
helm uninstall bifrost

# Delete PVCs (if you want to remove data)
kubectl delete pvc -l app.kubernetes.io/instance=bifrost

Scale

# Scale manually
kubectl scale deployment bifrost --replicas=5

# Or update via Helm
helm upgrade bifrost bifrost/bifrost \
  --set replicaCount=5 \
  --reuse-values

Monitoring

Prometheus Metrics

Bifrost exposes Prometheus metrics at /metrics. Enable ServiceMonitor for automatic scraping:

serviceMonitor:
  enabled: true
  interval: 30s
  scrapeTimeout: 10s

Health Checks

Check pod health:

# View pod status
kubectl get pods -l app.kubernetes.io/name=bifrost

# Check logs
kubectl logs -l app.kubernetes.io/name=bifrost --tail=100

# Describe pod
kubectl describe pod -l app.kubernetes.io/name=bifrost

Metrics Endpoints

# Port forward
kubectl port-forward svc/bifrost 8080:8080

# Check metrics
curl http://localhost:8080/metrics

# Check health
curl http://localhost:8080/health

Troubleshooting

Pod Not Starting

# Check events
kubectl describe pod -l app.kubernetes.io/name=bifrost

# Check logs
kubectl logs -l app.kubernetes.io/name=bifrost

# Common issues:
# - Image pull errors: Check repository access
# - PVC binding: Check PVC status
# - Config errors: Validate ConfigMap

Database Connection Issues

# For embedded PostgreSQL
kubectl exec -it deployment/bifrost-postgresql -- psql -U bifrost

# Check connectivity from pod
kubectl exec -it deployment/bifrost -- nc -zv bifrost-postgresql 5432

# Check secret
kubectl get secret bifrost-config -o yaml

High Memory Usage

# Check resource usage
kubectl top pods -l app.kubernetes.io/name=bifrost

# Increase limits
helm upgrade bifrost bifrost/bifrost \
  --set resources.limits.memory=4Gi \
  --reuse-values

Ingress Not Working

# Check ingress status
kubectl describe ingress bifrost

# Check ingress controller logs
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx

# Verify DNS
nslookup bifrost.yourdomain.com

Advanced Configuration

Custom Values File

Create my-values.yaml:

image:
  tag: "v1.3.37"  # Required: specify the Bifrost version

replicaCount: 3

storage:
  mode: postgres

postgresql:
  enabled: true
  auth:
    password: "secure-password"

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: bifrost.example.com
      paths:
        - path: /
          pathType: Prefix

bifrost:
  encryptionKey: "your-32-byte-key"
  providers:
    openai:
      keys:
        - value: "sk-..."
          weight: 1

Install:

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

Environment Variables

Add custom environment variables:

env:
  - name: CUSTOM_VAR
    value: "custom-value"

envFrom:
  - secretRef:
      name: bifrost-secrets
  - configMapRef:
      name: bifrost-config

Node Affinity

Deploy to specific nodes:

nodeSelector:
  node-type: ai-workload

affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app.kubernetes.io/name: bifrost
        topologyKey: kubernetes.io/hostname

tolerations:
  - key: "gpu"
    operator: "Equal"
    value: "true"
    effect: "NoSchedule"

Resources

Next Steps

Configure provider keys
Enable plugins
Set up monitoring
Configure ingress and TLS

Platform specific guides

Common setup instructions

Prerequisites

Quick Start

Add Helm Repository

Install Bifrost

Access Bifrost

Deployment Patterns

Development Setup

Configuration

Key Parameters

Secret Reference Parameters

Provider Configuration

Using Environment Variables for Provider Keys

Plugin Configuration

Operations

Upgrade

Rollback

Uninstall

Scale

Monitoring

Prometheus Metrics

Health Checks

Metrics Endpoints

Troubleshooting

Pod Not Starting

Database Connection Issues

High Memory Usage

Ingress Not Working

Advanced Configuration

Custom Values File

Environment Variables

Node Affinity

Resources

Next Steps

Platform specific guides

Common setup instructions

​Prerequisites

​Quick Start

​Add Helm Repository

​Install Bifrost

​Access Bifrost

​Deployment Patterns

​Development Setup

​Configuration

​Key Parameters

​Secret Reference Parameters

​Provider Configuration

​Using Environment Variables for Provider Keys

​Plugin Configuration

​Operations

​Upgrade

​Rollback

​Uninstall

​Scale

​Monitoring

​Prometheus Metrics

​Health Checks

​Metrics Endpoints

​Troubleshooting

​Pod Not Starting

​Database Connection Issues

​High Memory Usage

​Ingress Not Working

​Advanced Configuration

​Custom Values File

​Environment Variables

​Node Affinity

​Resources

​Next Steps

Prerequisites

Quick Start

Add Helm Repository

Install Bifrost

Access Bifrost

Deployment Patterns

Development Setup

Configuration

Key Parameters

Secret Reference Parameters

Provider Configuration

Using Environment Variables for Provider Keys

Plugin Configuration

Operations

Upgrade

Rollback

Uninstall

Scale

Monitoring

Prometheus Metrics

Health Checks

Metrics Endpoints

Troubleshooting

Pod Not Starting

Database Connection Issues

High Memory Usage

Ingress Not Working

Advanced Configuration

Custom Values File

Environment Variables

Node Affinity

Resources

Next Steps