> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Operar o Streaming Hub
> Faça o deploy do Streaming Hub com Helm em BYOC, rode migrações fora de banda, ligue as probes de liveness e readiness, defina a configuração essencial e observe o hub por OTLP.
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:
| Endpoint | Probe | Comportamento |
| ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/healthz` | Liveness | Devolve `200` incondicionalmente assim que o processo está servindo, independente da saúde do Postgres, do Kafka ou do consumidor de ingest da aplicação. Uma liveness que falha reinicia o pod, então ela não deve depender de dependências. |
| `/readyz` | Readiness | Reúne o conjunto completo de probes do papel. `Healthy` ou `Degraded` → `200` (mantido em rotação); `Down` → `503` (tirado de rotação). Uma réplica `Degraded` continua servindo. |
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:
| Variável | Padrão | Finalidade |
| -------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `STREAMING_HUB_ENV` | `local` | Ambiente de deploy (`local` \| `staging` \| `production`). Guia o portão de segurança de produção que rejeita as flags de bypass de desenvolvimento. |
| `STREAMING_HUB_ROLE` | `all` | Fatia implantável: `all` \| `ingest` \| `delivery`. Controla workers e clientes Kafka, nunca rotas. |
| `STREAMING_HUB_HTTP_LISTEN_ADDR` | `:8080` | O único endereço de bind do control plane. |
| `STREAMING_HUB_POSTGRES_DSN` | *(obrigatório)* | O DSN do PostgreSQL próprio do hub. O boot falha se estiver vazio. |
| `STREAMING_HUB_KAFKA_BROKERS` | *(vazio)* | Lista de brokers de bootstrap para o stream interno. |
| `STREAMING_HUB_TENANT_ID` | `default` | O id do tenant BYOC. Veja o aviso abaixo antes de mudá-lo. |
| `STREAMING_HUB_MANIFEST_SOURCES` | *(vazio)* | URLs base de produtores separadas por vírgula, cujos manifestos populam o catálogo no modo BYOC. URLs inválidas fazem o boot falhar. Esta variável é proibida no modo multi-tenant. |
| `STREAMING_HUB_MANIFEST_CLIENT_ID` | *(vazio)* | Client id opcional usado para buscar manifestos de produtores BYOC. Defina-o junto com o `STREAMING_HUB_MANIFEST_CLIENT_SECRET`; deixar os dois vazios usa buscas anônimas. |
| `STREAMING_HUB_MANIFEST_CLIENT_SECRET` | *(vazio)* | Client secret opcional para buscas de manifesto. Definir apenas uma credencial de manifesto faz o boot falhar. |
| `STREAMING_HUB_KEK_SOURCE` | `env` | Provedor da chave de criptografia de chaves (`env` \| `secretsmanager`). |
| `STREAMING_HUB_KEK_REF` | *(vazio)* | O **nome** da variável de ambiente que guarda o material da KEK — nunca o material em si. |
| `PLUGIN_AUTH_ADDRESS` | *(padrão do plugin-auth)* | A URL base do ponto de decisão do plugin-auth para a autorização do control plane. |
| `PLUGIN_AUTH_ENABLED` | `true` | Chave mestra de autenticação. `false` é um bypass local, **rejeitado em produção**. |
| `STREAMING_HUB_AUTODISABLE_ENABLED` | `true` | Kill switch para a desabilitação automática de destinos quebrados. |
| `STREAMING_HUB_SHUTDOWN_TIMEOUT` | `30s` | Janela de drenagem graciosa. A janela pré-parada mais `min(value, 55s)` deve ficar estritamente abaixo do lease de 60 segundos do dispatcher, ou o boot falha fechando. |
| `MULTI_TENANT_ENABLED` | `false` | `false` é BYOC de tenant único; `true` usa o Tenant Manager para a lista de tenants ativos, enquanto cada réplica capaz de ingest roda um consumidor Kafka de aplicação com `STREAMING_HUB_KAFKA_*`. |
| `MULTI_TENANT_URL` | *(obrigatório no modo multi-tenant)* | URL base do serviço Tenant Manager usada para a lista inicial e a atualização periódica. |
| `MULTI_TENANT_SERVICE_API_KEY` | *(obrigatório no modo multi-tenant)* | Credencial de serviço usada para autenticar requisições ao Tenant Manager. |
| `MULTI_TENANT_REDIS_HOST` | *(vazio; opcional no modo multi-tenant)* | Endpoint Redis opcional para atualizações de ciclo de vida de tenant quase em tempo real. Quando não definido, o listener não começa. A atualização periódica do Tenant Manager ainda converge a lista; em um pod apenas de delivery, a lista fica fixa até o restart. Configure a senha, o banco e os ajustes de TLS correspondentes quando seu deploy de Redis exigir. |
| `ENV_NAME` | *(obrigatório no modo multi-tenant)* | Segmento de ambiente no caminho `tenants/{ENV_NAME}/...` do Secrets Manager para as credenciais M2M por tenant de manifesto de produtor. |
| `STREAMING_HUB_AWS_HUB_PRINCIPAL_ARN` | *(vazio)* | O principal IAM público do hub embutido nos artefatos de configuração da AWS. Obrigatório para sinks AWS. |
| `STREAMING_HUB_AWS_SETUP_TEMPLATE_URL` | *(vazio)* | A URL pública do template CloudFormation para o link de criação rápida da AWS. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | *(vazio)* | O endpoint do collector OTLP para onde a telemetria exporta (sem o prefixo `STREAMING_HUB_`). |
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
***
As entranhas da entrega por trás das superfícies operacionais acima.
As operações de control plane que seus tenants usam.