Configuração de Gateway e Runtime

Esta página explica como configurar a camada opcional de gateway, usar serviços externos de dados e entender as configurações de runtime mais relevantes.

Padrões de implantação do gateway

O chart Helm suporta três padrões práticos para o gateway:

gateway embutido dentro do cluster
gateway externo
gateway embutido com um upstream OpenAI-compatible customizado

Gateway embutido

Esta é a opção recomendada quando você quer manter a implantação autocontida.

Use:

gateway:
  enabled: true

Quando habilitado:

a API usa o serviço de gateway dentro do cluster
o frontend pode chamar o gateway por meio do host configurado no ingress
o gateway pode expor /v1/models, /v1/chat/completions, /health e /metrics

Gateway externo

Se você já opera um gateway separado, mantenha o gateway embutido desabilitado e sobrescreva os 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"

Provider OpenAI-compatible customizado

Se você habilitar o gateway embutido, também pode configurar um upstream OpenAI-compatible gerenciado pelo 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"

Use esse modo quando:

você quer que o Smart Engineering chame um serviço LLM gerenciado pelo cliente
você ainda quer manter o contrato interno OpenAI-compatible do produto

PostgreSQL externo

A instalação padrão inclui PostgreSQL embutido. Para usar um banco externo:

postgres:
  enabled: false

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

Valkey externo ou serviço Redis-compatible

A instalação padrão inclui Valkey embutido. Para usar um serviço externo:

valkey:
  enabled: false

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

Mantenha esses serviços privados. Eles não foram feitos para exposição pública via ingress.

Configurações importantes de runtime

As configurações abaixo são as que normalmente mais mudam em ambientes de clientes.

Configuração	O que controla
`serviceAccount.name`	A service account Kubernetes usada pelos pods
`serviceAccount.annotations`	Anotações de IRSA ou de outro modelo de workload identity
`runtime.commonEnv.AWS_REGION`	Região AWS usada para Bedrock, S3, Marketplace e License Manager
`runtime.commonEnv.AWS_WORKLOAD_IDENTITY_MODE`	Modelo esperado de workload identity: `default_chain`, `irsa` ou `roles_anywhere`
`runtime.commonEnv.AUTH_MODE`	Modo de autenticação: `disabled` ou `oidc`
`runtime.commonEnv.AUTH_DISABLED`	Flag explícita de bypass de autenticação usada pela API e pelo gateway
`runtime.commonEnv.ALLOWED_ORIGINS`	Lista CORS de origens permitidas para a API
`runtime.commonEnv.LLM_GATEWAY_URL`	URL do gateway usada pelo backend
`runtime.commonEnv.S3_UPLOAD_SERVER_SIDE_ENCRYPTION`	Modo de criptografia do upload. `AES256` é o padrão. Use `aws:kms` apenas quando os buckets do cliente usarem KMS e a role IAM de runtime puder usar a chave
`s3.sourceBucket`	Bucket usado para os arquivos-fonte enviados
`s3.outputBucket`	Bucket usado para documentação e saídas geradas
`s3.workspaceBucket`	Bucket usado para artefatos internos de workspace
`bedrock.modelId`	Modelo Bedrock principal usado em tarefas mais pesadas
`bedrock.modelIdSmall`	Modelo Bedrock secundário usado em tarefas mais leves
`gateway.enabled`	Habilita o deployment do gateway embutido
`frontend.publicEnv.VITE_COMPASS_GATEWAY_BASE`	Endpoint do gateway usado pelo navegador para chat completions
`ingress.*`	Hosts públicos e configurações TLS
`postgres.enabled`	Habilita o stateful set embutido do PostgreSQL
`valkey.enabled`	Habilita o stateful set embutido do Valkey
`externalDatabase.*`	Referência ao secret do PostgreSQL externo
`externalValkey.*`	Configurações de conexão do Valkey externo

Observações operacionais

O produto mede o uso de análise de repositório via AWS Marketplace quando o metering está habilitado.
O perfil Marketplace espera ingestão baseada em S3 por meio do fluxo de callback da aplicação.
Chaves AWS estáticas não são recomendadas para deployments Marketplace.
Alterações de schema de banco são aplicadas pelo job de migração durante helm upgrade.

Próximos passos

Depois que o ambiente estiver em execução:

crie um projeto no Smart Engineering
faça upload de um arquivo-fonte compactado
confirme que o arquivo foi salvo no bucket de origem
execute uma task de documentação
verifique se os artefatos foram gravados no bucket de saída
consulte /config/runtime e /health se algo falhar na primeira execução

Padrões de implantação do gateway​

Gateway embutido​

Gateway externo​

Provider OpenAI-compatible customizado​

PostgreSQL externo​

Valkey externo ou serviço Redis-compatible​

Configurações importantes de runtime​

Observações operacionais​

Próximos passos​