--- title: "Deploying Bifrost on Kubernetes with Helm: Best Practices and Common Pitfalls" description: "Deploy Bifrost on Kubernetes with Helm using production-tested best practices, configuration patterns, and fixes for the most common deployment pitfalls.\n\nTeams adopting AI gateways at scale need a reproducible, declarative way to ship infrastructure into Kubernetes. The official chart makes it possible to deploy Bifrost on Kubernetes with Helm" image: https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w1200/2026/07/ChatGPT-Image-May-25--2026--09_54_28-AM.optimized.png --- Try Bifrost Enterprise free for 14 days. [Request access](https://www.getmaxim.ai/#enterprise-trial) *Deploy Bifrost on Kubernetes with Helm using production-tested best practices, configuration patterns, and fixes for the most common deployment pitfalls.* Teams adopting AI gateways at scale need a reproducible, declarative way to ship infrastructure into Kubernetes. The official chart makes it possible to deploy Bifrost on Kubernetes with Helm in minutes, but production-grade installs require more than a one-line `helm install`. This guide walks through the configuration patterns that hold up under load, the pitfalls that surface during the first incident, and the operational habits that keep a Bifrost cluster healthy across upgrades. Bifrost is the open-source AI gateway by Maxim AI, designed for high-throughput inference, governance, and reliability across [20+ LLM providers](https://docs.getbifrost.ai/providers/supported-providers/overview). ## Why Run Bifrost on Kubernetes Self-hosting an [AI gateway](https://www.getmaxim.ai/articles/top-5-llm-gateways-in-2026-a-production-ready-comparison/) on Kubernetes gives platform teams full control over data residency, governance, and scaling behavior. The Bifrost Helm chart packages the gateway as a first-class Kubernetes workload, with StatefulSet support for SQLite, optional embedded PostgreSQL, vector store integrations for [semantic caching](https://docs.getbifrost.ai/features/semantic-caching), and ingress, autoscaling, and probe configuration out of the box. Helm fits this workload well for three reasons: - **Declarative configuration**: every parameter in `values.yaml` maps to a field in the generated `config.json`, so the cluster state matches the chart input exactly. - **Reproducible rollouts**: the same values file can install, upgrade, and roll back across environments. - **Native Kubernetes primitives**: the chart produces standard Deployments, StatefulSets, Services, Ingress, HPAs, and ServiceAccounts that integrate with existing platform tooling. For teams comparing self-hosted AI gateways against managed alternatives, the [LLM Gateway Buyer's Guide](https://www.getmaxim.ai/resources/buyers-guide) covers the evaluation criteria that matter most for enterprise deployments. ## Prerequisites for a Bifrost Helm Deployment Before running `helm install`, confirm the cluster meets the chart's baseline requirements: - Kubernetes v1.19 or later, with `kubectl` configured against the target cluster. - [Helm 3.2.0 or later](https://helm.sh/docs/intro/install/) installed locally. - A persistent volume provisioner if you plan to use SQLite for storage. PostgreSQL-only deployments can skip this. - A [UTF8-encoded PostgreSQL database](https://www.postgresql.org/docs/current/multibyte.html) if you use Postgres for storage. Non-UTF8 databases will fail to initialize. - Kubernetes Secrets for the encryption key and any provider API keys you intend to inject at install time. Add the chart repository before the first install: ```bash helm repo add bifrost helm repo update ``` The full configuration surface, including every parameter and ready-made example files, lives in the [Helm values reference](https://docs.getbifrost.ai/deployment-guides/helm/values). ## Best Practices for Production Bifrost Helm Deployments The following practices reflect what production deployments of Bifrost consistently get right. ### Pin the image tag explicitly The chart requires `image.tag` to be set. Leaving it unset, or setting it to `latest`, will either fail at install time or pin the cluster to an undefined version that can drift between rollouts. Always specify a concrete version (for example, `v1.4.11`) and treat tag updates as deliberate, reviewed changes. ```bash helm install bifrost bifrost/bifrost --set image.tag=v1.4.11 ``` ### Externalize every secret Plain-text credentials in `values.yaml` are a frequent source of compliance findings. The Bifrost chart provides an `existingSecret` alternative for every sensitive field, including the encryption key, PostgreSQL password, vector store credentials, and per-provider API keys. Store these in Kubernetes Secrets, or integrate with [HashiCorp Vault and cloud key management services](https://docs.getbifrost.ai/enterprise/secret-management) on Bifrost Enterprise. ```yaml bifrost: encryptionKeySecret: name: "bifrost-encryption-key" key: "encryption-key" providerSecrets: openai: existingSecret: "provider-keys" key: "openai-api-key" envVar: "OPENAI_API_KEY" ``` ### Use PostgreSQL for production, not SQLite SQLite is convenient for local development and single-node demos, but it cannot back multi-replica deployments because PVCs are typically `ReadWriteOnce`. Production setups should use the chart's embedded PostgreSQL, an external managed Postgres (RDS, Cloud SQL, Azure Database), or a HA Postgres operator. Mixed-backend installs (Postgres for config, SQLite for logs) are supported through the `mixed-backend.yaml` example. ### Configure HPA with stream-aware behavior Bifrost handles long-lived SSE streams for chat completions. Default [Kubernetes HorizontalPodAutoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) settings can terminate active streams during scale-down, so override `scaleDown.stabilizationWindowSeconds` to a higher value and keep the `preStop` sleep in place so the load balancer drains before pods exit. ```yaml autoscaling: enabled: true minReplicas: 3 maxReplicas: 10 targetCPUUtilizationPercentage: 70 behavior: scaleDown: stabilizationWindowSeconds: 300 terminationGracePeriodSeconds: 60 lifecycle: preStop: exec: command: ["sh", "-c", "sleep 15"] ``` For deployments with long-running streams (over 45 seconds), raise `terminationGracePeriodSeconds` so the pod has time to finish in-flight responses. ### Spread replicas across nodes In HA deployments, place replicas on different nodes using [pod anti-affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity). This protects against single-node failures and helps the Kubernetes scheduler balance load across the cluster. ```yaml affinity: podAntiAffinity: requiredDuringSchedulingIgnoredDuringExecution: - labelSelector: matchLabels: app.kubernetes.io/name: bifrost topologyKey: kubernetes.io/hostname ``` ### Enable plugins through Helm values, not the UI Bifrost's built-in plugins (telemetry, logging, governance, semantic cache, OTel, Datadog) are configurable directly through Helm values. Managing them in `values.yaml` keeps the config reproducible across environments. For DB-backed deployments, increment the plugin `version` field when you want Helm-supplied config to overwrite an older record in the database. ```yaml bifrost: plugins: telemetry: enabled: true version: 1 logging: enabled: true version: 1 governance: enabled: true version: 1 ``` Pair plugin configuration with Bifrost's [virtual key governance](https://docs.getbifrost.ai/features/governance/virtual-keys) for per-team budgets, rate limits, and access control. The [Bifrost governance overview](https://www.getmaxim.ai/resources/governance) covers the full enterprise governance model. ### Enable observability from day one Bifrost ships native Prometheus metrics at `/metrics` and supports [OpenTelemetry tracing](https://docs.getbifrost.ai/features/observability) out of the box. Enable a `ServiceMonitor` to wire metrics into an existing Prometheus stack: ```yaml serviceMonitor: enabled: true interval: 30s scrapeTimeout: 10s ``` Bifrost's [performance benchmarks](https://www.getmaxim.ai/resources/benchmarks) document the 11 microsecond per-request overhead at 5,000 RPS, but real production performance depends on cluster topology and provider latency. Observability is the only way to verify the gateway is performing as expected. ## Common Pitfalls When Deploying Bifrost with Helm These are the failure modes that surface most often during the first production install or during a routine upgrade. ### Image pull errors from missing or expired registry secrets `ErrImagePull` and `ImagePullBackOff` show up when `image.tag` is unset, when the image repository points to a private enterprise registry without a valid pull secret, or when an ECR token has expired (ECR credentials expire after 12 hours). Use a credential helper or operator to refresh ECR tokens automatically rather than rotating them by hand. ### SQLite with multiple replicas Setting `replicaCount: 3` while leaving `storage.mode: sqlite` causes PVC binding failures because the chart's SQLite PVC uses `ReadWriteOnce`. Either move to PostgreSQL or keep `replicaCount: 1` for SQLite deployments. Production HA requires Postgres. ### Missing PVC provisioner A `Pending` PVC after install almost always means the cluster has no default storage class, or the configured `storageClass` does not exist. Verify with `kubectl get storageclass` and pin to a valid class. ```bash helm upgrade bifrost bifrost/bifrost \\ --reuse-values \\ --set storage.persistence.storageClass=standard ``` ### SSL mode mismatch with managed Postgres Most managed Postgres services (RDS, Cloud SQL, Azure Database) require SSL by default. Leaving `sslMode: disable` will cause connection failures. Set `sslMode: require` in the external Postgres config and rotate the credential into a Kubernetes Secret rather than embedding it in values. ### Encryption key key-name drift The `bifrost.encryptionKeySecret.key` parameter defaults to `encryption-key`, but many teams create the secret with the key name `key` (using `--from-literal=key=...`). Either match the default name in the secret, or override the parameter so it matches the secret's actual key. ### HPA dropping active SSE streams If scale-down events terminate streaming chat completions mid-response, raise `terminationGracePeriodSeconds` to at least 120 seconds, extend the `preStop` sleep, and increase `stabilizationWindowSeconds` to delay scale-down until traffic genuinely tapers. The Bifrost [troubleshooting guide](https://docs.getbifrost.ai/deployment-guides/helm/troubleshooting) documents the exact configuration. ### Data loss on `helm uninstall` `helm uninstall` does not remove PVCs by design, but a careless `kubectl delete pvc` will permanently destroy the gateway's data. Before any destructive operation, snapshot the PVC and use `storage.persistence.existingClaim` to re-attach data on reinstall. ## Operational Guidance: Upgrades, Rollbacks, and Scaling Helm makes day-2 operations predictable when the underlying values are managed in version control. - **Upgrades**: run `helm upgrade bifrost bifrost/bifrost -f your-values.yaml`. To change a single field without touching the rest, use `helm upgrade --reuse-values --set image.tag=v1.4.12`. - **Rollbacks**: `helm history bifrost` shows revision history; `helm rollback bifrost 2` reverts to a known good revision. - **Scaling**: prefer HPA-driven scaling over manual `kubectl scale`. For sudden bursts, scale up `minReplicas` rather than triggering an HPA reaction lag. - **Verification**: after any change, `kubectl get pods -l app.kubernetes.io/name=bifrost` and `curl /health` against a port-forwarded pod confirm the gateway is serving traffic. For multi-replica deployments that need [cluster mode and gossip-based peer discovery](https://docs.getbifrost.ai/enterprise/clustering), the chart provides headless service and service account permissions needed for Kubernetes-based discovery. ## Configuration Patterns for Common Deployment Scenarios The Helm chart ships ready-made example values files for the most common patterns under [`helm-charts/bifrost/values-examples/`](https://github.com/maximhq/bifrost/tree/main/helm-charts/bifrost/values-examples): - `sqlite-only.yaml`: minimal local or dev install. - `external-postgres.yaml`: point Bifrost at an existing managed Postgres instance. - `production-ha.yaml`: 3 replicas, embedded Postgres, Weaviate vector store, HPA, ingress. - `secrets-from-k8s.yaml`: every sensitive value sourced from Kubernetes Secrets. - `providers-and-virtual-keys.yaml`: all supported providers plus virtual key configurations. These files install directly from a raw URL, which makes them easy to use as a baseline and override per environment: ```bash helm install bifrost bifrost/bifrost \\ -f \\ --set image.tag=v1.4.11 ``` Teams running [MCP gateway workloads](https://www.getmaxim.ai/resources/mcp-gateway) on Kubernetes can add MCP server connections, tool filtering, and OAuth-based federated auth through the same values file, keeping the gateway and its tool catalog under unified config management. ## Get Started with Bifrost on Kubernetes A production-ready way to deploy Bifrost on Kubernetes with Helm requires more than the quickstart commands: explicit image pinning, externalized secrets, a real database, stream-aware autoscaling, pod anti-affinity, and observability wired in from day one. The Helm chart supports each of these patterns directly through `values.yaml`, and the example files in the repo cover most production scenarios as starting points. To see how Bifrost can simplify AI gateway infrastructure for your team, [book a demo with the Bifrost team](https://www.getmaxim.ai/book-a-demo) or explore the [Bifrost GitHub repository](https://github.com/maximhq/bifrost) to start with the open-source release. ## Read next [![OpenClaw vs Hermes: Which Agent to Run and How to Control It](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/openclaw-vs-hermes-which-agent-to-run-and-how-to-control-it-bifrost-1920x1080.png) OpenClaw and Hermes Agent are open-source, self-hosted AI agents that run on your own hardware and reach you through chat apps. This openclaw vs hermes guide compares how each is built and secured, says which to run for which job, and shows how to cap its models, spend, and MCP tools.](https://www.getmaxim.ai/articles/openclaw-vs-hermes-which-agent-to-run-and-how-to-control-it/) [![AnythingLLM With Every Model: Connect and Govern It Through One Gateway](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/anythingllm-with-every-model-connect-and-govern-it-through-o-bifrost-1920x1080.png) AnythingLLM is an open-source AI application for document chat, agents, and team workspaces. This guide shows how to route AnythingLLM through Bifrost so every workspace reaches any model through one endpoint, with budgets, rate limits, failover, and request logs.](https://www.getmaxim.ai/articles/anythingllm-with-every-model-connect-and-govern-it-through-one-gateway/) [![OWASP LLM Top 10: How to Cover Each Risk at the Gateway](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/10/owasp-llm-top-10-how-to-cover-each-risk-at-the-gateway-bifrost-1920x1080.png) The OWASP LLM Top 10 ranks the ten most critical security risks in applications built on large language models. This guide walks each 2026 risk, from prompt injection to unbounded consumption, and shows what an AI gateway such as Bifrost can enforce and where other controls are required.](https://www.getmaxim.ai/articles/owasp-llm-top-10-how-to-cover-each-risk-at-the-gateway/) ## More in AI Gateway [![Qwen-Coder vs Gemini 2.5 Pro Pricing for Long-Context Refactoring](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/07/ChatGPT-Image-May-25--2026--09_44_45-AM.optimized.png) Compare Qwen-Coder vs Gemini 2.5 Pro pricing for long-context refactoring, with worked cost examples at 50K, 200K, 500K, and 1M tokens. Refactoring at the repository level forces a hard pricing question: when an agent has to load 200K, 500K, or close to 1M tokens of code into](https://www.getmaxim.ai/articles/qwen-coder-vs-gemini-2-5-pro-pricing-for-long-context-refactoring/) [![Managing Virtual Keys and Budgets in Bifrost: A Complete Guide](https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w720/2026/07/ChatGPT-Image-May-25--2026--09_57_27-AM.optimized.png) Learn how virtual keys and budgets in Bifrost give platform teams hierarchical cost control, rate limits, and access governance across every LLM provider. Enterprise AI spending is now the fastest-growing line item in most engineering budgets, but the controls around it have not caught up. Gartner forecasts global AI](https://www.getmaxim.ai/articles/managing-virtual-keys-and-budgets-in-bifrost-a-complete-guide/) ```json { "@context": "https://schema.org", "@type": "Article", "publisher": { "@type": "Organization", "name": "Maxim Articles", "url": "https://www.getmaxim.ai/articles/", "logo": { "@type": "ImageObject", "url": "https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w256h256/2025/08/thumbnail.png", "width": 60, "height": 60 } }, "author": { "@type": "Person", "name": "Kuldeep Paul", "image": { "@type": "ImageObject", "url": "https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/2025/08/1727978381919.jpeg", "width": 800, "height": 800 }, "url": "https://www.getmaxim.ai/articles/author/kuldeep/", "sameAs": [] }, "headline": "Deploying Bifrost on Kubernetes with Helm: Best Practices and Common Pitfalls", "url": "https://www.getmaxim.ai/articles/deploying-bifrost-on-kubernetes-with-helm-best-practices-and-common-pitfalls/", "datePublished": "2026-05-22T04:19:00.000Z", "dateModified": "2026-10-16T06:13:14.000Z", "image": { "@type": "ImageObject", "url": "https://storage.ghost.io/c/84/03/8403f2f6-141c-411a-8f55-a32d4291533e/content/images/size/w1200/2026/07/ChatGPT-Image-May-25--2026--09_54_28-AM.optimized.png", "width": 1200, "height": 800 }, "keywords": "AI Gateway", "description": "Deploy Bifrost on Kubernetes with Helm using production-tested best practices, configuration patterns, and fixes for the most common deployment pitfalls.\n\nTeams adopting AI gateways at scale need a reproducible, declarative way to ship infrastructure into Kubernetes. The official chart makes it possible to deploy Bifrost on Kubernetes with Helm in minutes, but production-grade installs require more than a one-line helm install. This guide walks through the configuration patterns that hold up und", "mainEntityOfPage": "https://www.getmaxim.ai/articles/deploying-bifrost-on-kubernetes-with-helm-best-practices-and-common-pitfalls/" } ```