Skip to main content
Esta página é para operadores que rodam o Streaming Hub na própria infraestrutura (BYOC). Ela cobre o deploy, a configuração que importa, o contrato de saúde e desligamento, e como observar o serviço.

​
Deploy com Helm

O Streaming Hub vem como um Helm chart dedicado, o streaming-hub-helm, separado de qualquer outro chart de produto Lerian. O chart roda o hub em um de dois formatos:
  • all: um único deployment que roda todos os workers de segundo plano. Este é o padrão e o mais simples de operar.
  • split: deployments separados de ingest e delivery que escalam de forma independente: as réplicas de ingest compartilham um grupo de consumidores Kafka, enquanto as réplicas de delivery processam jobs de entrega do Postgres.
O formato split é guiado por processo pelo STREAMING_HUB_ROLE (all | ingest | delivery). O papel controla quais workers de segundo plano rodam e quais clientes Kafka discam. Ele não controla quais rotas HTTP sobem. Todo papel serve a API de control plane completa e, o que é decisivo, o endpoint /readyz de que seu orquestrador e sua coleta de métricas dependem. Há uma imagem e um binário. O papel é uma entrada de deploy, não de build.

​
Rodar migrações de banco de dados

O Streaming Hub usa um único banco PostgreSQL próprio do hub, e ele nunca migra a si mesmo. As migrações de schema rodam fora de banda. Um passo de migração separado (por exemplo, um hook PreSync do ArgoCD) aplica as migrações versionadas antes de o hub começar. No boot o hub apenas verifica que a versão de schema que espera está presente. Ele nunca roda uma migração como efeito colateral de começar. O hub provisiona por conta própria as partições semanais das suas tabelas com antecedência, como tarefa de segundo plano de rotina. Isso conta como manutenção interna, não como migração de schema. Não exige ação do operador, desde que o cron de partições continue rodando.

​
Saúde e desligamento gracioso

O Streaming Hub expõe dois endpoints de probe distintos. Ligue cada um à probe correspondente do Kubernetes: O /readyz distingue duas classes de falha. Uma falha de probe de runtime (Postgres inacessível, consumidor morto) leva a réplica a Down e para fora de rotação. Um degradador (latência elevada, atraso do consumidor, buffer de partição fino) prende a réplica em Degraded mas a mantém servindo. Uma réplica prejudicada não deve recusar tráfego. O conjunto de probes conhece o papel. Um consumidor de ingest ausente nunca deixa um pod de papel delivery sem readiness. Em um SIGTERM o hub drena com elegância. Ele vira o /readyz para NotReady primeiro, antes de parar de servir. Depois espera uma janela pré-parada limitada, para o orquestrador poder tirar o pod do serviço antes do encerramento das conexões. O endpoint /healthz fica em 200 o tempo todo, então o orquestrador não mata o pod no meio da drenagem. Ele então desmonta em ordem segura por dependência (HTTP, depois consumidor, depois dispatcher, depois as aplicações de segundo plano, depois os clientes Kafka, depois o pool, depois a telemetria).
Defina o terminationGracePeriodSeconds do deployment igual ou acima do teto de drenagem derivado do hub para o seu STREAMING_HUB_SHUTDOWN_TIMEOUT, não um número mágico fixo. No timeout de desligamento padrão de 30 segundos o teto fica em cerca de 80 segundos. Esse total é a janela pré-parada de 5 segundos mais o próprio timeout de desligamento. Ele também inclui uma etapa de drenagem do dispatcher de min(timeout, 55s) no pior caso e uma margem fixa de desmontagem para os componentes restantes.Um período de graça abaixo do teto arrisca um SIGKILL de uma réplica ainda drenando. Isso é seguro para a correção, mas abre mão da drenagem limpa. O hub recupera e reentrega os jobs em andamento, e o consumidor os deduplica.
O /version (identidade do build) e o /runtime (um retrato barato do runtime Go) completam a superfície operacional sem autenticação para triagem de incidentes.

​
Configuração essencial

O Streaming Hub lê a configuração de variáveis de ambiente STREAMING_HUB_*, mais as variáveis compartilhadas MULTI_TENANT_*, PLUGIN_AUTH_* e OTEL_* e a ENV_NAME sem prefixo. O inventário completo, com cada padrão, fica na referência de ambiente do serviço. As variáveis que você define com mais frequência: Remover uma URL do STREAMING_HUB_MANIFEST_SOURCES interrompe as futuras atualizações daquele produtor, mas mantém as linhas de catálogo dele que funcionavam por último. A atualização de manifesto é apenas descoberta no control plane. Uma queda de produtor não bloqueia a ingestão de eventos nem a correspondência de entrega. Valores de segredo nunca cabem em configuração comitada. Você referencia a KEK pelo nome da variável de ambiente em que a camada de deploy a injeta (STREAMING_HUB_KEK_REF). O hub lê o material daquela variável nomeada e nunca o registra em log. O material de SASL e TLS do Kafka no nível de deploy, a chave de API de serviço do Tenant Manager e as credenciais do Redis devem vir do seu cofre de segredos. As credenciais M2M por tenant para a descoberta de manifesto de produtor continuam no Secrets Manager.
O STREAMING_HUB_TENANT_ID define o tenant de control plane do BYOC. A ingestão aceita qualquer ce-tenantid não vazio. O hub grava um tenant diferente, mas esse tenant não consegue corresponder a subscriptions pertencentes a este tenant BYOC. Se você definir um valor diferente, as subscriptions devem usar aquele tenant. Caso contrário a ingestão passa, mas a entrega fica vazia. Um valor fora do padrão emite um aviso de inicialização. Preste atenção nele.

​
Forense de DLQ

O GET /admin/dlq é a superfície de forense do operador para observações de dead-letter. Ele é entre tenants por projeto. O escopo de admin da lib-auth o controla, ele não carrega shim de tenant e devolve registros de todos os tenants. Por isso ele não faz parte da API /v1 voltada ao cliente. As observações de dead-letter que ele lê servem apenas à observabilidade. Elas vêm dos tópicos de dead-letter de produtores upstream, e o hub nunca as reentrega. Use-o para investigar por que registros falharam upstream. Ele não os reproduz.

​
Conciliador de tópicos

O conciliador de tópicos é um detector de desvio apenas de leitura, habilitado por padrão (STREAMING_HUB_RECONCILER_ENABLED). A cada passada ele compara os tópicos vivos do broker, o catálogo de eventos e os alvos distintos de subscription. Ele sinaliza três tipos de desvio:
  • tópicos fantasma: um tópico seguido sem entrada de catálogo.
  • subscriptions mortas: um tipo de evento e major assinado sem entrada viva de catálogo.
  • quebras de atraso contra retenção.
Ele detecta, nunca corrige. Ele emite medidores apenas de contagem e logs estruturados, e não grava estado no broker nem no banco. Quando desabilitado, ele não cria goroutine e não disca cliente de admin, então o caminho desabilitado não custa nada. Um conciliador desabilitado perde um alarme operacional, mas nunca afeta a entrega.

​
Observabilidade

O Streaming Hub exporta suas métricas, traces e logs por OTLP (lib-observability), apontado para o collector em OTEL_EXPORTER_OTLP_ENDPOINT. É ali que ficam as métricas streaming_hub_* de verdade.
O endpoint /metrics é quase vazio por projeto: ele serve apenas o medidor estático streaming_hub_build_info. Colete as métricas de verdade do hub no seu collector OTLP, não no /metrics.
A identidade do tenant nunca é rótulo de métrica. Ela fica em atributos de span e campos de log, então a cardinalidade das métricas segue limitada, não importa quantos tenants um deploy atenda.

​
Próximos passos

Como o Streaming Hub funciona

As entranhas da entrega por trás das superfícies operacionais acima.

Gerenciar subscriptions

As operações de control plane que seus tenants usam.