devops-infra-helm-charts-gcp/helm-templates/bifrost/README.md

Bifrost Helm Charts

Official Helm charts for deploying Bifrost - a high-performance AI gateway with unified interface for multiple providers.

Latest Version: 2.0.14

Changelog

v2.0.14

• Added placement and order fields to custom plugin schema and template rendering
• Added plugin property completeness check to validate-helm-schema.sh
• Added custom plugin placement/order rendering tests to validate-helm-templates.sh
• Added PluginConfig struct validation to validate-go-config-fields.sh

v2.0.13

• Added missing client config properties: asyncJobResultTTL, requiredHeaders, loggingHeaders, allowedHeaders, mcpAgentDepth, mcpToolExecutionTimeout, mcpCodeModeBindingLevel, mcpToolSyncInterval, hideDeletedVirtualKeysInFilters
• Added MCP new fields: top-level toolSyncInterval, per-client clientId, isCodeModeClient, toolSyncInterval, isPingAvailable, toolPricing, and codeModeBindingLevel in tool manager config
• Added governance modelConfigs and providers top-level properties
• Added cluster region property
• Added guardrail provider timeout field (was missing from schema and template rendering)
• Fixed isPingAvailable rendering bug in _helpers.tpl (was using wrong key name)
• Added is_ping_available and tool_pricing to config.schema.json MCP client config
• Added new CI script validate-go-config-fields.sh for Go struct-to-schema drift detection
• Expanded all 3 existing CI validation scripts with Gap 1-8 property coverage

v2.0.12

• Fixed health probe paths to use /health instead of /metrics

v2.0.11

• Bumped appVersion to 1.4.11

v2.0.10

• Added missing plugin config properties from Go implementations:
  • governance: required_headers, is_enterprise
  • logging: disable_content_logging, logging_headers
  • otel: headers, tls_ca_cert, insecure
  • telemetry: custom_labels

v2.0.9

• Bumped appVersion to 1.4.8

v2.0.8

• Added comprehensive config field coverage for all config.schema.json fields
• Added Pinecone vector store support (external only) with secret injection
• Added governance routing rules template support
• Added OTEL metrics fields (metrics_enabled, metrics_endpoint, metrics_push_interval)
• Added advanced Redis connection pool fields (pool_size, timeouts, idle conns, etc.)
• Added Weaviate timeout and className fields
• Expanded values.yaml with commented examples for all provider types (Azure, Vertex, Bedrock), network config, concurrency, proxy config, and governance entities
• Added helm config field validation CI test (246 assertions covering all config.schema.json fields)

v2.0.7

• Previous release

v2.0.6

• Fixes MCP client config template to convert camelCase Helm values to snake_case config format

v2.0.5

• Fixes config field validation parity

v2.0.2

• Added Qdrant vector store support with deployment, service, and PVC templates
• Added headless service template for StatefulSet DNS resolution
• Fixed gitignore pattern that was excluding template files from version control

v2.0.1

• Added missing StatefulSet template for SQLite with persistence mode
• Added headless service for StatefulSet DNS resolution
• v2.0.0 documented StatefulSet support but the template was not included - this release fixes that

v2.0.0 (Breaking Change)

StatefulSet for SQLite with Persistence

This release fixes the multi-attach volume error when running multiple replicas with SQLite storage mode.

What Changed

• When using storage.mode: sqlite with storage.persistence.enabled: true, Bifrost now deploys as a StatefulSet instead of a Deployment
• Each pod gets its own dedicated PersistentVolumeClaim (e.g., data-bifrost-0, data-bifrost-1, data-bifrost-2)
• A headless service is created for StatefulSet DNS resolution
• HorizontalPodAutoscaler now correctly references StatefulSet or Deployment based on storage configuration

Who Is Affected

• Users running SQLite mode with persistence enabled and multiple replicas
• Users upgrading existing SQLite deployments need to migrate (see below)

Who Is NOT Affected

• Users running PostgreSQL mode (storage.mode: postgres) - no changes, still uses Deployment
• Users running SQLite without persistence (storage.persistence.enabled: false)
• Users running SQLite with an existing PVC claim (storage.persistence.existingClaim)

Migration Guide for Existing SQLite Deployments

Since Kubernetes doesn't allow in-place conversion from Deployment to StatefulSet, you need to:

1. Back up your data (if needed)
2. Uninstall the existing release: helm uninstall bifrost
3. Delete the old PVC: kubectl delete pvc bifrost-data
4. Install with the new chart version: helm install bifrost bifrost/bifrost --set image.tag=<latest-image>

Note: For production high-availability setups, we recommend using PostgreSQL mode which scales horizontally without these concerns.

v1.7.0

• Previous stable release with Deployment-based architecture for all storage modes

Quick Start

# Add the Bifrost Helm repository
helm repo add bifrost https://maximhq.github.io/bifrost/helm-charts

# Update your local Helm chart repository cache
helm repo update

# Install Bifrost with default configuration (SQLite storage)
helm install bifrost bifrost/bifrost --set image.tag=v1.4.3

Prerequisites

• Kubernetes 1.23+
• Helm 3.2.0+
• PV provisioner support in the underlying infrastructure (for persistent storage)

Installation

From Helm Repository (Recommended)

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

# Install with default values
helm install bifrost bifrost/bifrost --set image.tag=v1.4.3

# Or install with custom values
helm install bifrost bifrost/bifrost -f my-values.yaml

From Source

# Clone the repository
git clone https://github.com/maximhq/bifrost.git
cd bifrost/helm-charts

# Install from local chart
helm install bifrost ./bifrost --set image.tag=v1.5.2

Interactive Installation

Use the included installation script for guided setup:

cd bifrost/helm-charts/bifrost
./scripts/install.sh

Configuration

Image Configuration

Parameter	Description	Default
image.repository	Container image repository	docker.io/maximhq/bifrost
image.tag	Container image tag (required)	""
image.pullPolicy	Image pull policy	IfNotPresent

Important: You must specify the image.tag. See available tags at Docker Hub.

Enterprise Private Registry

For enterprise customers with private container registries, simply override the image.repository with your full registry URL:

# Google Artifact Registry
image:
  repository: us-west1-docker.pkg.dev/bifrost-enterprise/your-org/bifrost
  tag: v1.5.0

# AWS ECR
image:
  repository: 123456789.dkr.ecr.us-east-1.amazonaws.com/bifrost
  tag: v1.5.0

# Azure Container Registry
image:
  repository: yourregistry.azurecr.io/bifrost
  tag: v1.5.0

# Self-hosted registry
image:
  repository: registry.yourcompany.com/ai/bifrost
  tag: v1.5.0

If your private registry requires authentication, configure imagePullSecrets:

image:
  repository: us-west1-docker.pkg.dev/bifrost-enterprise/your-org/bifrost
  tag: v1.5.0

imagePullSecrets:
  - name: my-registry-secret

Create the secret beforehand:

kubectl create secret docker-registry my-registry-secret \
  --docker-server=us-west1-docker.pkg.dev \
  --docker-username=_json_key \
  --docker-password="$(cat key.json)" \
  --docker-email=your-email@example.com

Storage Configuration

Bifrost supports two storage backends (SQLite and PostgreSQL) that can be configured independently for config and logs stores.

Parameter	Description	Default
storage.mode	Default storage backend (fallback when per-store type not set)	sqlite
storage.persistence.enabled	Enable persistent storage for SQLite	true
storage.persistence.size	Storage size	10Gi
storage.configStore.enabled	Enable configuration store	true
storage.configStore.type	Config store backend: sqlite, postgres, or ""	"" (uses storage.mode)
storage.logsStore.enabled	Enable logs store	true
storage.logsStore.type	Logs store backend: sqlite, postgres, or ""	"" (uses storage.mode)

Mixed Backend Example

You can use different backends for config and logs stores:

storage:
  mode: sqlite  # Default fallback
  configStore:
    enabled: true
    type: sqlite   # Config in SQLite (fast, local)
  logsStore:
    enabled: true
    type: postgres # Logs in PostgreSQL (scalable, queryable)

postgresql:
  enabled: true
  # ... PostgreSQL configuration for logs store

PostgreSQL Configuration

Parameter	Description	Default
postgresql.enabled	Deploy PostgreSQL	false
postgresql.auth.username	Database username	bifrost
postgresql.auth.password	Database password	bifrost_password
postgresql.auth.database	Database name	bifrost
postgresql.external.enabled	Use external PostgreSQL	false
postgresql.external.host	External PostgreSQL host	""

Vector Store Configuration (Semantic Caching)

Bifrost supports multiple vector stores for semantic caching:

Parameter	Description	Default
vectorStore.enabled	Enable vector store	false
vectorStore.type	Vector store type: none, weaviate, redis, qdrant	none

Weaviate

vectorStore:
  enabled: true
  type: weaviate
  weaviate:
    enabled: true  # Deploy Weaviate
    # Or use external:
    # external:
    #   enabled: true
    #   host: "weaviate.example.com"

Redis

vectorStore:
  enabled: true
  type: redis
  redis:
    enabled: true  # Deploy Redis
    # Or use external:
    # external:
    #   enabled: true
    #   host: "redis.example.com"

Qdrant

vectorStore:
  enabled: true
  type: qdrant
  qdrant:
    enabled: true  # Deploy Qdrant
    # Or use external:
    # external:
    #   enabled: true
    #   host: "qdrant.example.com"

Bifrost Application Configuration

Parameter	Description	Default
bifrost.port	Application port	8080
bifrost.host	Bind address	0.0.0.0
bifrost.logLevel	Log level	info
bifrost.logStyle	Log format: json or text	json
bifrost.encryptionKey	Encryption key for sensitive data	""

Provider Configuration

Configure AI provider API keys:

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

Plugins Configuration

Plugin	Parameter	Description
Telemetry	bifrost.plugins.telemetry.enabled	Enable metrics collection
Logging	bifrost.plugins.logging.enabled	Enable request logging
Governance	bifrost.plugins.governance.enabled	Enable budget management
Semantic Cache	bifrost.plugins.semanticCache.enabled	Enable semantic caching
OTEL	bifrost.plugins.otel.enabled	Enable OpenTelemetry integration
Maxim	bifrost.plugins.maxim.enabled	Enable Maxim observability
Datadog	bifrost.plugins.datadog.enabled	Enable Datadog APM integration
Custom	bifrost.plugins.custom	Array of custom/dynamic plugins

Custom Plugins

You can add custom/dynamic plugins using the bifrost.plugins.custom array:

bifrost:
  plugins:
    custom:
      - name: "my-custom-plugin"
        enabled: true
        path: "/plugins/my-plugin.so"
        version: 1
        placement: "pre_builtin"  # or "post_builtin" (default)
        order: 0                  # execution order within placement group
        config:
          key: value

Client Configuration

Parameter	Description	Default
bifrost.client.disableDbPingsInHealth	Disable DB pings in health check	false
bifrost.client.headerFilterConfig.allowlist	Headers allowed to forward to LLM providers	[]
bifrost.client.headerFilterConfig.denylist	Headers blocked from forwarding	[]

MCP Configuration

Parameter	Description	Default
bifrost.mcp.enabled	Enable MCP (Model Context Protocol)	false
bifrost.mcp.clientConfigs	Array of MCP client configurations	[]
bifrost.mcp.toolManagerConfig.toolExecutionTimeout	Tool execution timeout in seconds	30
bifrost.mcp.toolManagerConfig.maxAgentDepth	Maximum agent depth	10

Ingress Configuration

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  hosts:
    - host: bifrost.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: bifrost-tls
      hosts:
        - bifrost.example.com

Auto-scaling Configuration

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80
  targetMemoryUtilizationPercentage: 80

Example Configurations

The chart includes pre-configured examples in values-examples/:

Configuration	Description
sqlite-only.yaml	Simple setup with SQLite (local development)
postgres-only.yaml	PostgreSQL for config and logs
mixed-backend.yaml	SQLite for config + PostgreSQL for logs (mixed backend)
postgres-weaviate.yaml	PostgreSQL + Weaviate for semantic caching
postgres-redis.yaml	PostgreSQL + Redis for semantic caching
postgres-qdrant.yaml	PostgreSQL + Qdrant for semantic caching
sqlite-weaviate.yaml	SQLite + Weaviate
sqlite-redis.yaml	SQLite + Redis
sqlite-qdrant.yaml	SQLite + Qdrant
external-postgres.yaml	Using external PostgreSQL
production-ha.yaml	Production high-availability setup

Using Example Configurations

# From Helm repository
helm install bifrost bifrost/bifrost \
  -f https://raw.githubusercontent.com/maximhq/bifrost/main/helm-charts/bifrost/values-examples/postgres-only.yaml \
  --set image.tag=v1.5.2

# From local source
helm install bifrost ./bifrost -f ./bifrost/values-examples/postgres-only.yaml

Production Deployment

For production deployments, we recommend:

1. Use PostgreSQL for reliable data persistence
2. Enable semantic caching with Weaviate, Redis, or Qdrant
3. Configure auto-scaling for handling variable load
4. Set up Ingress with TLS termination
5. Use external secrets for sensitive data

Example Production Setup

# production-values.yaml
replicaCount: 3

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10

storage:
  mode: postgres

postgresql:
  enabled: true
  auth:
    password: "SECURE_PASSWORD_HERE"
  primary:
    persistence:
      size: 50Gi

vectorStore:
  enabled: true
  type: weaviate
  weaviate:
    enabled: true
    persistence:
      size: 50Gi

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  hosts:
    - host: bifrost.yourdomain.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: bifrost-tls
      hosts:
        - bifrost.yourdomain.com

bifrost:
  client:
    initialPoolSize: 1000
    allowedOrigins:
      - "https://yourdomain.com"
  plugins:
    semanticCache:
      enabled: true
    telemetry:
      enabled: true
    logging:
      enabled: true

Upgrading

# Update repository
helm repo update

# Upgrade release
helm upgrade bifrost bifrost/bifrost --set image.tag=v1.5.2

# Or with custom values
helm upgrade bifrost bifrost/bifrost -f my-values.yaml

Uninstalling

# Uninstall release
helm uninstall bifrost

# If you want to delete persistent volumes
kubectl delete pvc -l app.kubernetes.io/name=bifrost

Accessing Bifrost

After installation, access Bifrost using one of these methods:

Port Forwarding (Development)

kubectl port-forward svc/bifrost 8080:8080
# Then visit http://localhost:8080

LoadBalancer

service:
  type: LoadBalancer

Ingress

Configure the ingress section as shown above.

Monitoring

Bifrost exposes Prometheus metrics at /metrics:

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

For OpenTelemetry integration:

bifrost:
  plugins:
    otel:
      enabled: true
      config:
        service_name: "bifrost"
        collector_url: "http://otel-collector:4317"
        trace_type: "otel"
        protocol: "grpc"

Troubleshooting

Check Pod Status

kubectl get pods -l app.kubernetes.io/name=bifrost
kubectl describe pod <pod-name>

View Logs

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

Check Configuration

# View generated configmap
kubectl get configmap bifrost -o yaml

# View generated secrets
kubectl get secret bifrost -o yaml

Common Issues

Pod stuck in Pending state:

• Check if PersistentVolume is available: kubectl get pv
• Check storage class: kubectl get storageclass

Pod CrashLoopBackOff:

• Check logs: kubectl logs <pod-name>
• Verify environment variables and secrets

Cannot connect to PostgreSQL:

• Ensure PostgreSQL pod is running
• Check connection string in configmap/secrets
• Verify network policies allow connectivity

Resources

• Bifrost Documentation
• GitHub Repository
• Docker Hub
• Discord Community

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Built with ❤️ by Maxim