← Volver al listado de tecnologías ← Índice de Bifrost

Despliegue en producción y camino a Enterprise

Por: Artiko
bifrostdesplieguekuberneteshelmclusteringenterprise

Despliegue en producción y camino a Enterprise

En el capítulo 13 aprendiste a embeber Bifrost dentro de tu propia aplicación Go usando el SDK. Hasta ahora hemos corrido Bifrost en local: un solo proceso, una base de datos SQLite, un puerto expuesto y nada más. Eso es perfecto para desarrollar y para entender cada pieza, pero producción es otra historia. En producción tu gateway es el camino crítico de todas las llamadas a modelos: si se cae, se caen tus agentes, tus features de IA y tus integraciones. Necesita aguantar carga, sobrevivir al reinicio de un nodo, escalar horizontalmente y no perder presupuestos ni rate limits cuando corren varias réplicas a la vez.

Este capítulo cierra el tutorial. Vamos a llevar Bifrost de “funciona en mi máquina” a “funciona bajo carga, con redundancia y observabilidad”. Empezamos endureciendo el contenedor de Docker, subimos a Kubernetes con Helm, montamos un cluster de alta disponibilidad con estado compartido, conectamos agentes CLI como Claude Code y Cursor, y finalmente vemos cuándo y cómo dar el salto de la versión open source (OSS) a Bifrost Enterprise. Todo lo que es exclusivo de Enterprise queda marcado de forma explícita para que sepas exactamente qué puedes hacer con el binario gratuito y qué requiere licencia.

1. Docker tuning para producción

La imagen de Docker que usaste en el capítulo 2 corre con valores por defecto pensados para empezar rápido. Para producción hay que afinar cuatro cosas: el runtime de Go, los límites de recursos, la persistencia de datos y los healthchecks.

Variables de entorno del runtime

Bifrost está escrito en Go, así que las dos variables que más impacto tienen son las del recolector de basura. GOGC controla cada cuánto corre el garbage collector (valores más altos lo hacen menos seguido, a cambio de más memoria) y GOMEMLIMIT fija un límite suave de memoria para que el runtime libere agresivamente antes de que el contenedor sea matado por OOM. La regla práctica es poner GOMEMLIMIT en torno al 90% del límite de memoria del contenedor.

GOGC=200
GOMEMLIMIT=3600MiB
LOG_LEVEL=info
LOG_STYLE=json

En producción siempre conviene LOG_STYLE=json: los logs estructurados son los que tu stack de observabilidad (que viste en el capítulo 11) puede parsear sin esfuerzo. Deja LOG_LEVEL=info salvo que estés depurando un incidente, en cuyo caso debug te da el detalle completo.

docker-compose endurecido

Este es un docker-compose.yml listo para producción que junta límites de recursos, ulimits, healthcheck y política de reinicio. Fíjate en cómo apuntamos la base de datos a Postgres en vez de SQLite (volveremos sobre el porqué en la sección de clustering).

services:
  bifrost:
    image: maximhq/bifrost:latest
    ports:
      - "8080:8080"
    environment:
      - GOGC=200
      - GOMEMLIMIT=3600MiB
      - LOG_LEVEL=info
      - LOG_STYLE=json
      - BIFROST_DB_TYPE=postgres
      - BIFROST_DB_DSN=postgres://user:pass@postgres:5432/bifrost?sslmode=disable
    volumes:
      - bifrost-data:/app/data
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "-O", "/dev/null",
             "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 4G
        reservations:
          cpus: '2'
          memory: 2G

volumes:
  bifrost-data:

Tres detalles que marcan la diferencia:

Tuning de concurrencia en config.json

El runtime es solo la mitad. La otra mitad vive en tu config.json (el archivo que conociste en el capítulo 3). Por proveedor puedes ajustar el tamaño del pool de concurrencia y el buffer de cola, y a nivel de cliente el tamaño inicial del pool de objetos:

{
  "providers": {
    "openai": {
      "concurrency_and_buffer_size": {
        "concurrency": 1000,
        "buffer_size": 1500
      }
    }
  },
  "client": {
    "initial_pool_size": 3000
  }
}

Las fórmulas recomendadas por la documentación son:

No copies números a ciegas: parten de tu carga real. Mide tu RPS pico con las métricas de Prometheus del capítulo 11 y aplica las fórmulas a partir de ahí.

2. Kubernetes con Helm

Docker Compose es excelente para un solo host. Cuando necesitas varias réplicas, autoscaling y rolling updates, el destino natural es Kubernetes, y Bifrost publica un chart oficial de Helm.

Instalar el chart

Primero registras el repositorio de charts de Maxim AI y lo actualizas:

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

La instalación mínima para OSS necesita fijar la versión de imagen y referenciar un Secret de Kubernetes con la clave de cifrado (Bifrost cifra las credenciales sensibles en reposo, por eso es obligatoria):

helm install bifrost bifrost/bifrost \
  --set image.tag=v1.4.11 \
  --set bifrost.encryptionKeySecret.name="bifrost-encryption-key" \
  --set bifrost.encryptionKeySecret.key="encryption-key"

El chart vive en bifrost/bifrost y está publicado también en Artifact Hub.

Valores clave del values.yaml

Los campos que más vas a tocar:

CampoPara qué sirve
image.tagVersión de la imagen (obligatorio, ej. v1.4.11).
bifrost.encryptionKeySecretReferencia al Secret con la clave de cifrado.
bifrost.providersMapeo de claves API de proveedores (OpenAI, Anthropic, etc.).
replicaCountNúmero de réplicas (3 para HA).
postgresql.enabledActiva Postgres para persistencia.
pluginsMódulos de telemetría, logging y governance.

Para los recursos de cada pod, los valores recomendados para producción son:

resources:
  limits:
    cpu: "4"
    memory: "4Gi"
  requests:
    cpu: "2"
    memory: "2Gi"

Y para alta disponibilidad activas réplicas más autoscaling:

replicaCount: 3
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10

Storage externo: por qué SQLite no escala

El chart soporta dos modos de almacenamiento: SQLite (con un PVC de unos 10Gi) o PostgreSQL (50Gi+ para producción). Aquí está la clave que define toda tu arquitectura: SQLite es single-node. Su modelo de un solo escritor es incompatible con varias réplicas escribiendo a la vez. En el momento en que pones replicaCount: 3, necesitas Postgres como backend compartido:

postgresql:
  enabled: true

Postgres almacena la configuración y los logs de forma centralizada, de modo que las tres réplicas ven el mismo estado. Sin este paso, cada réplica tendría su propia config aislada y los rate limits y presupuestos del capítulo 9 no se respetarían de forma global.

Operaciones de ciclo de vida

El día a día de un chart desplegado:

# Actualizar reutilizando los valores actuales
helm upgrade bifrost bifrost/bifrost --reuse-values

# Actualizar desde tu archivo de valores
helm upgrade bifrost bifrost/bifrost -f your-values.yaml

# Subir solo la version de imagen
helm upgrade bifrost bifrost/bifrost --reuse-values --set image.tag=v1.4.11

# Rollback a la revision anterior (o a una concreta)
helm rollback bifrost
helm rollback bifrost 2

# Desinstalar y limpiar los PVC
helm uninstall bifrost
kubectl delete pvc -l app.kubernetes.io/instance=bifrost

El helm rollback es tu botón de emergencia: si una nueva versión se comporta mal, vuelves a la revisión anterior en segundos.

3. Clustering y alta disponibilidad

Tener tres réplicas con replicaCount: 3 te da redundancia de proceso, pero no necesariamente estado compartido coherente a nivel de cluster. El cluster mode de Bifrost es lo que sincroniza rate limits, contadores de presupuesto y datos de governance entre todos los pods.

Exclusivo de Enterprise: el cluster mode (bifrost.cluster.*) es una capacidad de Enterprise. Las imágenes OSS aceptan estos valores pero no ejecutan el cluster mode en runtime. Con OSS puedes correr varias réplicas compartiendo Postgres, pero la sincronización activa de estado vía gossip es Enterprise.

Cómo funciona el cluster mode

Según la documentación, el cluster mode permite que múltiples réplicas de Bifrost compartan estado (rate limits, contadores de presupuesto y datos de governance) entre pods. Requiere PostgreSQL como backend de almacenamiento (SQLite es single-node) y usa descubrimiento de pares (peer discovery) basado en gossip con comunicación gRPC entre nodos.

Los puertos por defecto son:

Métodos de peer discovery

Bifrost soporta varios mecanismos para que los pods se encuentren entre sí:

TipoCómo descubre los pares
KubernetesConsulta la API de Kubernetes para encontrar pods de Bifrost por label selector.
DNSResuelve las IPs de los pares con el DNS de un headless service.
Static PeersEnumera explícitamente las direcciones de los pares.
ConsulUsa serviceName y consulAddress.
etcdRequiere serviceName y el array etcdEndpoints.
mDNSIdeal para desarrollo local o clusters bare-metal.

Valores de Helm para cluster mode

bifrost:
  cluster:
    enabled: true
    gossip:
      port: 7946
    grpc:
      port: 10102
    region: "us-east-1"   # etiquetado de region (opcional)
storage:
  mode: postgres

Para el descubrimiento por Kubernetes, los pods necesitan permisos de RBAC para ["list", "get", "watch"] sobre el recurso ["pods"]. Antes de desplegar creas los secrets de credenciales:

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

kubectl create secret generic bifrost-encryption \
  --from-literal=encryption-key='your-32-byte-encryption-key'

Y despliegas con tu archivo de valores de cluster:

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

Topología de un despliegue HA

Así se ve un despliegue de alta disponibilidad: varias réplicas de Bifrost repartidas en nodos distintos (gracias a podAntiAffinity), todas hablando con el mismo Postgres y sincronizando estado vía gossip.

flowchart TB
    Client[Clientes / Agentes / SDKs] --> LB[Service / Ingress LoadBalancer]
    LB --> P1[Bifrost Pod 1<br/>Nodo A]
    LB --> P2[Bifrost Pod 2<br/>Nodo B]
    LB --> P3[Bifrost Pod 3<br/>Nodo C]
    P1 <-. gossip 7946 / gRPC 10102 .-> P2
    P2 <-. gossip 7946 / gRPC 10102 .-> P3
    P1 <-. gossip 7946 / gRPC 10102 .-> P3
    P1 --> PG[(PostgreSQL<br/>config + logs + estado)]
    P2 --> PG
    P3 --> PG
    P1 --> Providers[OpenAI / Anthropic / Bedrock / ...]
    P2 --> Providers
    P3 --> Providers

Para que ese cluster sea de verdad resiliente, la configuración de producción recomendada incluye:

¿Cuándo necesitas clustering?

No todos necesitan un cluster. Una sola instancia bien dimensionada cubre muchísima carga. Da el salto a clustering cuando se cumpla alguno de estos:

4. Despliegue gestionado: fly.io y ECS

Si no quieres operar Kubernetes, hay caminos más livianos. Bifrost es una imagen de contenedor estándar, así que corre en cualquier plataforma que ejecute contenedores.

En cualquiera de estos casos los principios de las secciones anteriores siguen valiendo: Postgres externo para estado compartido, GOMEMLIMIT al 90% de la memoria asignada, healthcheck sobre /health y logs en formato JSON.

5. Bifrost Enterprise: qué desbloquea

La versión OSS de Bifrost es completa y suficiente para muchísimos casos. Enterprise es un superset que añade capacidades pensadas para organizaciones grandes con requisitos de cumplimiento, seguridad y escala. Estas son las funcionalidades exclusivas de Enterprise tal como las nombra la documentación:

Funcionalidad EnterpriseQué aporta
Adaptive Load BalancingEscalado predictivo con monitoreo de salud de proveedores en tiempo real; el tráfico se desvía automáticamente al upstream más rápido disponible.
ClusteringClustering de alta disponibilidad con descubrimiento automático, sincronización de estado por gossip y despliegues rolling sin downtime.
Role-Based Access Control (RBAC)Roles personalizados con permisos granulares sobre cada recurso de Bifrost.
Data Access ControlAlcance a nivel de fila, para que cada operador vea solo lo que su rol permite.
Advanced GovernanceGovernance jerárquica entre equipos, clientes y unidades de negocio.
Access ProfilesPolíticas reutilizables de proveedor, modelo, presupuesto y rate-limit.
Audit LogsTrazas de auditoría inmutables y con timestamp para cada cambio de configuración.
Log ExportsExportación automática de logs de request y telemetría a S3, GCS, BigQuery y otros data lakes.
Datadog ConnectorIntegración nativa con Datadog APM, LLM Observability y métricas, con tracing completo de requests.
User Provisioning (OIDC)Login OIDC con sincronización de usuarios y grupos desde el directorio.
GuardrailsContent safety con AWS Bedrock Guardrails, Azure Content Safety, Google Model Armor, CrowdStrike AIDR, GraySwan y Patronus AI.
Secrets DetectionDetecta claves API, credenciales y tokens en prompts y respuestas antes de que salgan de tu perímetro.
Custom RegexPatrones específicos de tu organización para redacción o rechazo.
MCP Tool GroupsBundles curados de herramientas MCP asignables a virtual keys, equipos, clientes, usuarios, proveedores o API keys.
In-VPC DeploymentsDespliegue dentro de tu nube privada, sin tráfico cruzando los límites de la red pública.

Nota la diferencia con OSS: el load balancing del capítulo 7 reparte tráfico, pero el adaptive load balancing (predictivo, según salud en tiempo real) es Enterprise. Igual con el MCP Gateway del capítulo 10: los MCP Tool Groups jerárquicos son Enterprise.

6. Guardrails (Enterprise)

Los Guardrails dan content safety, validación de seguridad y enforcement de políticas sobre los requests y las respuestas de los LLM. Su arquitectura gira en torno a dos conceptos:

Una sola rule puede enlazar varios profiles para una protección en capas. Una rule tiene, entre otras, estas propiedades: cel_expression (la lógica CEL), apply_to (input, output o both), sampling_rate (porcentaje de requests evaluados, 0-100), timeout (límite en segundos) y provider_config_ids (los profiles enlazados).

Ejemplos de expresiones CEL:

# Siempre aplicar
true

# Solo mensajes del usuario
request.messages.exists(m, m.role == "user")

# Filtrado por contenido
request.messages.exists(m, m.content.contains("confidential"))

# Reglas por modelo
request.model.startsWith("gpt-4")

Proveedores de guardrails soportados

La plataforma soporta ocho proveedores: Secrets Detection (detección respaldada por Gitleaks de claves, tokens y credenciales filtradas), Custom Regex (guardrails regex in-process, incluye una plantilla de PII Detection), AWS Bedrock Guardrails, Azure Content Safety, Google Model Armor, CrowdStrike AIDR, GraySwan Cygnal y Patronus AI.

Un profile nativo de detección de secretos se ve así:

{
  "id": 1,
  "provider_name": "secrets",
  "policy_name": "Block Leaked Credentials",
  "enabled": true,
  "config": {
    "ignored_secret_keywords": ["example", "dummy"]
  }
}

Y uno de regex para PII (detección de email y números de seguridad social de EE.UU.):

{
  "id": 2,
  "provider_name": "regex",
  "policy_name": "PII Detection",
  "enabled": true,
  "config": {
    "patterns": [
      {
        "pattern": "\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}\\b",
        "description": "Email address",
        "flags": "i"
      },
      {
        "pattern": "\\b\\d{3}-\\d{2}-\\d{4}\\b",
        "description": "US Social Security Number"
      }
    ]
  }
}

Para integrar un proveedor externo como AWS Bedrock, el profile referencia el ARN del guardrail y las credenciales vía variables de entorno:

{
  "id": 3,
  "provider_name": "bedrock",
  "policy_name": "PII Detection Profile",
  "enabled": true,
  "config": {
    "access_key": "env.AWS_ACCESS_KEY_ID",
    "secret_key": "env.AWS_SECRET_ACCESS_KEY",
    "guardrail_arn": "arn:aws:bedrock:us-east-1:123456789:guardrail/abc123",
    "guardrail_version": "1",
    "region": "us-east-1"
  }
}

Aplicar guardrails a un request

Los guardrails se enganchan vía headers personalizados o desde el cuerpo del request:

# Un solo guardrail
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-guardrail-id: bedrock-prod-guardrail"

# Varios guardrails (secuenciales)
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-guardrail-ids: bedrock-prod-guardrail,azure-content-safety-001"

O configurados en el cuerpo, separando input y output:

{
  "bifrost_config": {
    "guardrails": {
      "input": ["bedrock-prod-guardrail"],
      "output": ["patronus-ai-001"],
      "async": false
    }
  }
}

El manejo de respuestas usa códigos propios: 200 (pasó la validación, con metadata de tiempos), 246 (warning: el request continúa pero con redacciones o modificaciones registradas) y 446 (bloqueado por guardrails, con el detalle de los tipos de violación, categorías, severidad y confianza). Manejar esos códigos en tu cliente es lo que te permite reaccionar a una violación de PII o a un intento de prompt injection.

7. Agentes CLI: Bifrost como backend de Claude Code y Cursor

Una de las formas más potentes de usar Bifrost en el día a día es ponerlo como backend de tus agentes CLI. Bifrost expone endpoints 100% compatibles con las APIs de OpenAI, Anthropic y Gemini, así que casi cualquier herramienta que hable esos protocolos puede apuntar a tu gateway en vez de ir directo al proveedor. Así centralizas claves, observabilidad, load balancing y governance para todas tus herramientas de golpe. Esto es la culminación del drop-in replacement del capítulo 5: cambiar la base URL.

Un detalle importante de la base URL

La forma de la URL varía según el cliente. Herramientas como Codex CLI requieren que la base API termine en /v1 (por ejemplo https://your-gateway/openai/v1), mientras que los SDK oficiales de OpenAI normalmente toman https://your-gateway/openai y añaden /v1 internamente en las rutas. Confundir esto es la causa número uno de errores de integración: revisa qué espera tu cliente concreto.

Claude Code

Para conectar el MCP Gateway de Bifrost a Claude Code:

claude mcp add --transport http bifrost http://localhost:8080/mcp

Y si usas una virtual key (las del capítulo 9) para restringir el acceso a solo las herramientas que esa key permite:

claude mcp add-json bifrost '{"type":"http","url":"http://localhost:8080/mcp","headers":{"Authorization":"Bearer bf-virtual-key"}}'

Reemplaza bf-virtual-key por tu virtual key real. El acceso queda limitado a las herramientas permitidas por la configuración de esa key.

Otros agentes

La documentación cubre también LibreChat, Open WebUI, Cursor, Zed Editor, Codex CLI, Gemini CLI y Qwen Code. En todos el patrón es el mismo: apuntar la base URL al endpoint compatible de Bifrost (/openai, /anthropic o /gemini) y, si hace falta, pasar la virtual key como Authorization o X-Api-Key.

Un detalle sobre headers: por defecto Bifrost solo deja pasar una lista blanca (Content-Type, Authorization, X-Requested-With, X-Stainless-Timeout y X-Api-Key). Si tu agente envía headers personalizados y la integración falla, cambia la whitelist a *.

Lo que ganas al pasar todos tus agentes por Bifrost:

8. El camino de OSS a Enterprise

Enterprise es un superset de OSS: todo proveedor, plugin, integración y campo de config.json que usas en OSS sigue funcionando en Enterprise sin cambios. Las integraciones del SDK, los plugins personalizados (del capítulo 12) y los servidores MCP se transfieren tal cual. Eso significa que no reescribes tu integración: actualizas la infraestructura.

La diferencia crítica: la base de datos

Enterprise no soporta SQLite como almacén de config o de logs. La razón es la misma que vimos en clustering: el modelo de un solo escritor de SQLite es incompatible con el clustering HA y las réplicas multi-region. Tienes que migrar a PostgreSQL antes de actualizar. Sirve cualquier Postgres de producción: RDS, Aurora, Cloud SQL, AlloyDB, Azure Database for PostgreSQL, Crunchy Bridge o un PG 16+ autogestionado.

La herramienta recomendada para la migración es pgloader, que hace una migración de una sola pasada de SQLite a PostgreSQL:

# Instalacion
sudo apt-get install pgloader   # Linux
brew install pgloader           # macOS

# Migracion
pgloader ./bifrost.db postgresql://bifrost:PASSWORD@postgres-host:5432/bifrost

Restricción clave: detén el gateway OSS antes de migrar, para que no caigan escrituras en SQLite después de tomar el snapshot.

Checklist de migración

flowchart LR
    A[Snapshot del .db<br/>y parar el gateway OSS] --> B[Provisionar PostgreSQL<br/>de produccion]
    B --> C[Correr pgloader<br/>y verificar row counts]
    C --> D[Actualizar config.json<br/>al DSN de PostgreSQL]
    D --> E[Aplicar security hardening<br/>antes de exponer trafico]
    E --> F[Arrancar Enterprise]
  1. Haz snapshot de tu archivo SQLite y detén el gateway OSS.
  2. Provisiona un PostgreSQL de producción.
  3. Corre pgloader y verifica los row counts.
  4. Actualiza la URL de la base de datos en config.json al DSN de PostgreSQL.
  5. Aplica el security hardening antes de exponer el gateway al tráfico.

¿Cuándo dar el salto?

Considera Enterprise cuando aparezca alguno de estos disparadores:

La documentación también referencia guías separadas sobre sizing y redundancia (dimensionar pods y hardware de base de datos), topología cross-region y security hardening (controles no negociables antes de exponerte a producción). Sea cual sea tu plan, esos tres pilares (dimensionar bien, distribuir geográficamente si hace falta, y endurecer la seguridad) son los que separan un despliegue que aguanta de uno que se cae el primer día de carga real.

Resumen

Cerramos el tutorial llevando Bifrost de local a producción. Aprendiste a endurecer el contenedor de Docker con GOGC/GOMEMLIMIT, límites de recursos, ulimits, healthcheck sobre /health y volumen persistente, además del tuning de concurrency, buffer_size e initial_pool_size en config.json. Subiste a Kubernetes con el chart oficial de Helm (helm repo add bifrost https://maximhq.github.io/bifrost/helm-charts), viste los valores clave (image.tag, encryptionKeySecret, replicaCount, autoscaling) y entendiste por qué Postgres es obligatorio en cuanto pasas de una sola réplica. Montaste mentalmente un cluster HA con peer discovery por gossip y gRPC (recordando que el cluster mode activo es Enterprise), y conociste alternativas gestionadas como fly.io y ECS.

En la segunda mitad recorriste Enterprise: adaptive load balancing, RBAC, audit logs, OIDC/SSO, in-VPC, MCP Tool Groups y los Guardrails con sus ocho proveedores (Secrets Detection, Custom Regex, AWS Bedrock, Azure Content Safety, Google Model Armor, CrowdStrike AIDR, GraySwan y Patronus AI), enganchados vía headers x-bf-guardrail-id. Conectaste agentes CLI como Claude Code (claude mcp add) y Cursor apuntando la base URL a Bifrost, con la advertencia de la terminación /v1 según el cliente. Y trazaste el camino OSS -> Enterprise: migrar de SQLite a PostgreSQL con pgloader, parar el gateway antes de migrar, y aplicar security hardening antes de exponer tráfico.

Con esto completas el recorrido “de 0 a héroe” de Bifrost: desde tu primer request hasta un gateway de producción con alta disponibilidad, governance, observabilidad y un plan claro de evolución hacia Enterprise. El siguiente paso es tuyo: levanta tu propio gateway, conecta tus agentes y mide el impacto en costo, latencia y control. Vuelve al índice del tutorial cuando quieras repasar cualquier pieza.

Volver al índice del tutorial

← Volver al listado de tecnologías ← Índice de Bifrost