Skip to main content
Latest Chart Version: View on Artifact Hub

Prerequisites

  • Kubernetes cluster (v1.19+)
  • kubectl configured
  • Helm 3.2.0+ installed
  • Persistent Volume provisioner (required for SQLite; optional for Postgres-only)
If you use PostgreSQL for Bifrost storage, ensure the database is UTF8 encoded. See PostgreSQL UTF8 Requirement.

Step 1 - Add the Helm Repository

Step 2 - Install

The Helm chart ships ready-made values files under helm-charts/bifrost/values-examples/. For example: sqlite-only.yaml, production-ha.yaml, external-postgres.yaml, and secrets-from-k8s.yaml. See the full list here: https://github.com/maximhq/bifrost/tree/main/helm-charts/bifrost/values-examples
Fastest way to get running. Bifrost deploys as a StatefulSet with a 10Gi PVC for SQLite.
image.tag is required - the chart will not start without it. Check Docker Hub for available versions.

Step 3 - Verify

Step 4 - Configure Providers & Plugins

Next steps: jump to Next Steps.

Operations

Upgrade

Rollback

Scale

Uninstall


Monitoring

Prometheus Metrics

Bifrost exposes Prometheus metrics at /metrics (/<prefix>/metrics through an ingress when bifrost.server.basePath is set). If you run the Prometheus Operator (for example through kube-prometheus-stack), enable the bundled ServiceMonitor for automatic scraping. The monitoring.coreos.com/v1 CRDs must be installed when the manifest is applied; rendering does not need them, so helm template, Argo CD and Flux work offline.
The ServiceMonitor scrapes the service’s http port directly, so its path stays /metrics even when bifrost.server.basePath is set. Scraping with auth enabled. When bifrost.authConfig.isEnabled or bifrost.governance.authConfig.isEnabled is on, /metrics requires credentials too. An unauthenticated scrape gets a 401 and the target sits at up=0 without any error. Turn on basicAuth so the scrape sends the admin credentials:
  • In the release namespace, basicAuth inherits the Secret and key names from the active bifrost.governance.authConfig (preferred) or bifrost.authConfig. If you set serviceMonitor.namespace to another namespace, set serviceMonitor.basicAuth.existingSecret (and usernameKey / passwordKey) to a Secret in that namespace.
  • Bifrost reads the Secret as environment variables at pod start, so restart the pods after rotating it (kubectl rollout restart); until then scrapes get 401.
  • For a bearer token instead, set serviceMonitor.authorization.credentials to a Secret key reference. It cannot be combined with basicAuth.
  • The render fails rather than producing a ServiceMonitor that can never scrape: when no Secret can be resolved, when both auth methods are set, when authorization has no credentials, or when bifrost.plugins.telemetry.config.metrics_enabled is false (/metrics then returns 404).
The scrape credentials are admin credentials. Bifrost has no metrics-only credential: the basic-auth admin credentials, a base64 username:password bearer token and a session token all grant the same access as the dashboard and management API.
  • The Prometheus Operator copies the referenced credentials into the configuration it generates for Prometheus, so they also live in the Prometheus namespace. Restrict who can read Secrets there and in the ServiceMonitor’s namespace.
  • With the default http scheme they cross the pod network in plain text on every scrape. Use scheme: https with tlsConfig when Bifrost serves TLS, or a service mesh that encrypts pod-to-pod traffic.
Do not make /metrics public by adding it to bifrost.client.whitelistedRoutes unless the ingress blocks it. The default ingress routes every path (path: /, pathType: Prefix), so a whitelisted /metrics (and /<prefix>/metrics with bifrost.server.basePath) is reachable from outside the cluster, and its labels carry customer, team, user and virtual key names and IDs. If you whitelist it, exclude /metrics at the ingress and limit in-cluster access to Prometheus with a NetworkPolicy.

Health Checks

Check pod health:

Metrics Endpoints


Configuration Guides

Values Reference

All parameters, secret references, advanced config, example patterns

Client Configuration

Pool size, logging, CORS, header filtering, compat shims, MCP settings

Provider Setup

OpenAI, Anthropic, Azure, Bedrock, Vertex, Groq, self-hosted

Storage

SQLite, PostgreSQL, ClickHouse logs, object storage for logs, vector stores

Plugins

Telemetry, logging, semantic cache, OTel, Datadog, governance

Governance

Budgets, rate limits, virtual keys, routing rules

Alerting

Alert channels, CEL rules, history retention, webhook network controls

Cluster Mode

Multi-replica HA, gossip, peer discovery

Troubleshooting

Pod startup, database, ingress, PVC, secrets, performance

Secret Management

AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Azure Key Vault - vault references in provider keys and credentials

Resources

Next Steps

  1. Configure provider keys
  2. Enable plugins
  3. Set up observability
  4. Configure governance