Configuración de Gateway y Runtime

Esta página explica cómo configurar la capa opcional de gateway, usar servicios externos de datos y entender las configuraciones de runtime más relevantes.

Patrones de despliegue del gateway

El chart Helm soporta tres patrones prácticos para el gateway:

gateway embebido dentro del clúster
gateway externo
gateway embebido con un upstream OpenAI-compatible personalizado

Gateway embebido

Esta es la opción recomendada cuando quieres que el despliegue siga siendo autocontenido.

Usa:

gateway:
  enabled: true

Cuando está habilitado:

la API usa el servicio de gateway dentro del clúster
el frontend puede llamar al gateway mediante el host configurado en ingress
el gateway puede exponer /v1/models, /v1/chat/completions, /health y /metrics

Gateway externo

Si ya operas un gateway separado, mantén deshabilitado el gateway embebido y sobrescribe los valores de runtime:

gateway:
  enabled: false

runtime:
  commonEnv:
    LLM_GATEWAY_URL: "https://gateway.example.com"

frontend:
  publicEnv:
    VITE_COMPASS_GATEWAY_BASE: "https://gateway.example.com/v1/chat/completions"

Proveedor OpenAI-compatible personalizado

Si habilitas el gateway embebido, también puedes configurar un upstream OpenAI-compatible administrado por el cliente:

gateway:
  enabled: true
  env:
    CUSTOM_PROVIDER_ENABLED: "true"
    CUSTOM_PROVIDER_BASE_URL: "https://llm.example.com"
    CUSTOM_PROVIDER_API_SHAPE: "openai"
    CUSTOM_PROVIDER_API_KEY: ""
    CUSTOM_PROVIDER_HEADERS_JSON: '{"x-tenant":"buyer-a"}'
    CUSTOM_PROVIDER_MODELS_JSON: >-
      [{"id":"gpt-4.1","name":"GPT 4.1","context_window":128000,"supports_streaming":true,"supports_function_calling":true,"input_modalities":["text"],"output_modalities":["text"]}]
    CUSTOM_PROVIDER_DEFAULT_MODEL: "gpt-4.1"
    CUSTOM_PROVIDER_LABEL: "Buyer OpenAI-Compatible"

Usa este modo cuando:

quieres que Smart Engineering llame a un servicio LLM administrado por el cliente
quieres mantener el contrato interno OpenAI-compatible del producto

PostgreSQL externo

La instalación por defecto incluye PostgreSQL embebido. Para usar una base externa:

postgres:
  enabled: false

externalDatabase:
  existingSecretName: smart-eng-database
  existingSecretKey: DATABASE_URL

Valkey externo o servicio Redis-compatible

La instalación por defecto incluye Valkey embebido. Para usar un servicio externo:

valkey:
  enabled: false

externalValkey:
  host: "valkey.example.internal"
  port: 6379
  tlsEnabled: true
  username: ""
  existingSecretName: smart-eng-valkey
  existingSecretPasswordKey: redis-password

Mantén estos servicios privados. No están pensados para exponerse públicamente mediante ingress.

Configuraciones importantes de runtime

Las siguientes configuraciones son las que más suelen ajustarse en entornos de clientes.

Configuración	Qué controla
`serviceAccount.name`	La service account de Kubernetes usada por los pods
`serviceAccount.annotations`	Anotaciones de IRSA o de otro modelo de workload identity
`runtime.commonEnv.AWS_REGION`	Región AWS usada para Bedrock, S3, Marketplace y License Manager
`runtime.commonEnv.AWS_WORKLOAD_IDENTITY_MODE`	Modelo esperado de workload identity: `default_chain`, `irsa` o `roles_anywhere`
`runtime.commonEnv.AUTH_MODE`	Modo de autenticación: `disabled` u `oidc`
`runtime.commonEnv.AUTH_DISABLED`	Flag explícita de bypass de autenticación usada por la API y el gateway
`runtime.commonEnv.ALLOWED_ORIGINS`	Lista CORS de orígenes permitidos para la API
`runtime.commonEnv.LLM_GATEWAY_URL`	URL del gateway usada por el backend
`runtime.commonEnv.S3_UPLOAD_SERVER_SIDE_ENCRYPTION`	Modo de cifrado de la subida. `AES256` es el valor por defecto. Usa `aws:kms` solo cuando los buckets del cliente usen KMS y el rol IAM de runtime pueda utilizar esa clave
`s3.sourceBucket`	Bucket usado para los archivos fuente subidos
`s3.outputBucket`	Bucket usado para la documentación y las salidas generadas
`s3.workspaceBucket`	Bucket usado para artefactos internos de workspace
`bedrock.modelId`	Modelo Bedrock principal usado en tareas más pesadas
`bedrock.modelIdSmall`	Modelo Bedrock secundario usado en tareas más livianas
`gateway.enabled`	Habilita el deployment del gateway embebido
`frontend.publicEnv.VITE_COMPASS_GATEWAY_BASE`	Endpoint del gateway usado por el navegador para chat completions
`ingress.*`	Hosts públicos y configuración TLS
`postgres.enabled`	Habilita el stateful set embebido de PostgreSQL
`valkey.enabled`	Habilita el stateful set embebido de Valkey
`externalDatabase.*`	Referencia al secret del PostgreSQL externo
`externalValkey.*`	Configuración de conexión del Valkey externo

Notas operativas

El producto mide el uso de análisis de repositorios a través de AWS Marketplace cuando el metering está habilitado.
El perfil Marketplace espera ingestión basada en S3 mediante el flujo de callback de la aplicación.
No se recomiendan claves AWS estáticas para despliegues Marketplace.
Los cambios de esquema de base de datos se aplican mediante el job de migración durante helm upgrade.

Próximos pasos

Después de que el entorno esté funcionando:

crea un proyecto en Smart Engineering
sube un archivo fuente comprimido
confirma que el archivo se guardó en el bucket de origen
ejecuta una tarea de documentación
verifica que los artefactos se escribieron en el bucket de salida
revisa /config/runtime y /health si algo falla en la primera ejecución

Patrones de despliegue del gateway​

Gateway embebido​

Gateway externo​

Proveedor OpenAI-compatible personalizado​

PostgreSQL externo​

Valkey externo o servicio Redis-compatible​

Configuraciones importantes de runtime​

Notas operativas​

Próximos pasos​