Operando o Streaming Hub

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

​

Fazendo o deploy com Helm

---

O Streaming Hub é distribuído como um Helm chart dedicado, streaming-hub-helm, separado de qualquer outro chart de produto Lerian. O chart roda o hub em uma de duas formas:

• all — um único deployment que roda todos os workers de background. É 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 único consumer group Kafka, enquanto as réplicas de delivery processam os jobs de entrega a partir do Postgres.

A forma split é dirigida por processo por STREAMING_HUB_ROLE (all | ingest | delivery). A role controla quais workers de background rodam e quais clients Kafka discam — ela não controla quais rotas HTTP são montadas. Toda role serve a API de control-plane completa e, crucialmente, o endpoint /readyz do qual o seu orquestrador e o scrape de métricas dependem. Há uma única imagem e um único binário; a role é uma entrada de deployment, não de build.

​

Rodando migrations de banco de dados

---

O Streaming Hub é respaldado por um único banco de dados PostgreSQL de propriedade do hub, e ele nunca migra a si mesmo. As migrations de schema rodam out of band — como um passo de migração separado (por exemplo, um hook PreSync do ArgoCD) que aplica as migrations versionadas antes do hub iniciar. No boot, o hub apenas verifica que a versão de schema que ele espera está presente; ele nunca roda uma migration como efeito colateral de iniciar. O hub de fato provisiona antecipadamente as suas próprias partições de tabela semanais como uma tarefa de background de rotina — isso é manutenção interna, não uma migration de schema, e não requer ação do operador além de deixar o cron de partições rodando.

​

Saúde e desligamento gracioso

---

O Streaming Hub expõe dois endpoints de probe distintos. Conecte cada um ao probe correspondente do Kubernetes: O /readyz distingue duas classes de falha. Uma falha de runtime-probe — Postgres inacessível, consumidor morto — leva a réplica para Down e para fora da rotação. Um degrader — latência elevada, lag do consumidor, um buffer de partição fino — prende a réplica em Degraded, mas a mantém servindo, porque uma réplica prejudicada não deveria recusar tráfego. O conjunto de probes é role-aware: um pod de role delivery não é marcado como não pronto por não ter consumidor de ingest. No SIGTERM, o hub drena graciosamente. Ele vira o /readyz para NotReady primeiro — antes de parar de servir — e espera uma janela pre-stop limitada para que o orquestrador possa retirar o pod do serviço antes que as conexões sejam cortadas. O /healthz permanece 200 o tempo todo, de modo que o pod não é morto no meio da drenagem. Ele então desmonta em ordem segura por dependência (HTTP, depois consumidor, depois dispatcher, depois os apps de background, depois os clients Kafka, depois o pool, depois a telemetria). O /version (identidade do build) e o /runtime (um snapshot barato do runtime Go) completam a superfície operacional não autenticada para triagem de incidentes.

​

Configuração essencial

---

O Streaming Hub lê a sua configuração de variáveis de ambiente STREAMING_HUB_* (mais algumas variáveis compartilhadas PLUGIN_AUTH_* e OTEL_*). O inventário completo, com todos os defaults, está na referência de ambiente do serviço. As variáveis que você define com mais frequência: Valores de segredo nunca pertencem a essas variáveis em produção. A KEK é referenciada pelo nome da variável de ambiente na qual a camada de deploy a injeta (STREAMING_HUB_KEK_REF); o hub lê o material daquela variável nomeada e nunca o loga. As credenciais SASL, a CA de TLS e as credenciais do tenant-manager seguem a mesma regra — a variável contém o valor em runtime, mas o valor vem do seu secret store, não de um arquivo de configuração commitado.

​

Análise forense de DLQ

---

O GET /admin/dlq é a superfície de análise forense do operador para observações de dead-letter. Ele é cross-tenant por design: é protegido pelo escopo admin do lib-auth, não carrega nenhum shim de tenant e retorna registros de todos os tenants, então não faz parte da API /v1 voltada ao cliente. As observações de dead-letter que ele lê são apenas observabilidade — são capturadas dos tópicos de dead-letter dos produtores upstream e nunca são re-entregues pelo hub. Use-o para investigar por que os registros falharam upstream; ele não os reprocessa.

​

Reconciliador de tópicos

---

O reconciliador de tópicos é um detector de drift somente leitura, habilitado por padrão (STREAMING_HUB_RECONCILER_ENABLED). A cada passagem ele compara os tópicos ativos do broker, o catálogo de eventos e os destinos distintos das assinaturas, e sinaliza três tipos de drift: tópicos fantasma (um tópico seguido sem entrada no catálogo), assinaturas mortas (um tipo de evento e major assinado sem entrada viva no catálogo) e violações de lag-versus-retenção. Ele detecta, nunca corrige — emite gauges apenas de contagem e logs estruturados, e não grava nenhum estado no broker ou no banco de dados. Quando desabilitado, ele não gera goroutine alguma e não disca client admin algum, então o caminho desabilitado não custa nada; desabilitá-lo perde um alarme operacional, mas nunca afeta a entrega.

​

Observabilidade

---

O Streaming Hub exporta suas métricas, traces e logs através de OTLP (lib-observability), apontado para o coletor em OTEL_EXPORTER_OTLP_ENDPOINT. É lá que vivem as métricas streaming_hub_* de verdade. A identidade do tenant nunca é um label de métrica — ela vive em atributos de span e campos de log — de modo que a cardinalidade das métricas permanece limitada não importa quantos tenants um deployment atenda.

​

Próximos passos

---