Saltar al contenido principal
Esta página es para operadores que ejecutan Streaming Hub en su propia infraestructura (BYOC). Cubre el despliegue, la configuración que importa, el contrato de salud y apagado, y cómo observar el servicio.

​
Desplegar con Helm

Streaming Hub se distribuye como un chart de Helm dedicado, streaming-hub-helm, separado de cualquier otro chart de producto de Lerian. El chart ejecuta el hub en una de dos formas:
  • all — un único deployment que ejecuta todos los workers de segundo plano. Este es el valor por defecto y el más simple de operar.
  • split — deployments ingest y delivery separados que escalan de forma independiente: las réplicas de ingest comparten un único grupo de consumidores de Kafka, mientras que las réplicas de delivery procesan los trabajos de entrega desde Postgres.
La forma split se controla por proceso con STREAMING_HUB_ROLE (all | ingest | delivery). El rol controla qué workers de segundo plano se ejecutan y qué clientes de Kafka marcan; no controla qué rutas HTTP se montan. Cada rol sirve la API del plano de control completa y, sobre todo, el endpoint /readyz del que dependen tu orquestador y el scrape de métricas. Hay una sola imagen y un solo binario; el rol es una entrada de despliegue, no de compilación.

​
Ejecutar migraciones de base de datos

Streaming Hub está respaldado por una única base de datos PostgreSQL propiedad del hub, y nunca se migra a sí mismo. Las migraciones de esquema se ejecutan fuera de banda —como un paso de migración separado (por ejemplo, un hook PreSync de ArgoCD) que aplica las migraciones versionadas antes de que el hub arranque. En el arranque, el hub solo verifica que la versión de esquema que espera está presente; nunca ejecuta una migración como efecto secundario del arranque. El hub sí aprovisiona con antelación sus propias particiones de tabla semanales como una tarea rutinaria de segundo plano; eso es mantenimiento interno, no una migración de esquema, y no requiere ninguna acción del operador más allá de dejar el cron de particiones en ejecución.

​
Salud y apagado ordenado

Streaming Hub expone dos endpoints de sonda distintos. Conecta cada uno a la sonda de Kubernetes correspondiente: /readyz distingue dos clases de fallo. Un fallo de sonda de runtime —Postgres inalcanzable, consumidor muerto— lleva la réplica a Down y fuera de rotación. Un degradador —latencia elevada, lag del consumidor, un buffer de particiones escaso— fija la réplica en Degraded pero la mantiene sirviendo, porque una réplica deteriorada no debería rechazar tráfico. El conjunto de sondas tiene en cuenta el rol: un pod con rol delivery no se marca como no listo por no tener un consumidor de ingest. Ante SIGTERM, el hub drena de forma ordenada. Cambia /readyz a NotReady primero —antes de dejar de servir— y espera una ventana pre-stop acotada para que el orquestador pueda sacar el pod del servicio antes de que se corten las conexiones. /healthz permanece en 200 durante todo el proceso, así que el pod no se mata a mitad del drenaje. Luego desmonta en un orden seguro respecto a las dependencias (HTTP, luego el consumidor, luego el dispatcher, luego las apps de segundo plano, luego los clientes de Kafka, luego el pool y luego la telemetría).
Establece el terminationGracePeriodSeconds del deployment en el techo de drenaje derivado del hub para tu STREAMING_HUB_SHUTDOWN_TIMEOUT, o por encima, no en un número mágico fijo. Con el timeout de apagado por defecto de 30 segundos, el techo es de unos 80 segundos: la ventana pre-stop de 5 segundos, más el propio timeout de apagado, más un tramo de drenaje del dispatcher en el peor caso de min(timeout, 55s), más un margen fijo de desmontaje para los componentes restantes. Un periodo de gracia por debajo del techo arriesga un SIGKILL de una réplica que aún está drenando —seguro para la correctitud (los trabajos en vuelo se reclaman y se reenvían, deduplicados en el consumidor), pero se pierde el drenaje limpio.
/version (identidad de compilación) y /runtime (una instantánea barata del runtime de Go) completan la superficie operativa no autenticada para el triaje de incidentes.

​
Configuración esencial

Streaming Hub lee su configuración de variables de entorno STREAMING_HUB_* (más unas cuantas variables compartidas PLUGIN_AUTH_* y OTEL_*). El inventario completo, con cada valor por defecto, está en la referencia de entorno del servicio. Las variables que estableces con más frecuencia: Los valores de los secretos nunca pertenecen a estas variables en producción. La KEK se referencia por el nombre de la variable de entorno en la que la capa de despliegue la inyecta (STREAMING_HUB_KEK_REF); el hub lee el material de esa variable nombrada y nunca lo registra en logs. Las credenciales de SASL, de CA de TLS y del tenant manager siguen la misma regla: la variable contiene el valor en tiempo de ejecución, pero el valor proviene de tu almacén de secretos, no de un archivo de configuración versionado.
STREAMING_HUB_TENANT_ID es una trampa de cero entregas en BYOC. El hub solo acepta eventos cuyo ce-tenantid coincida exactamente con este valor; todos los demás eventos se descartan en silencio (unknown_or_inactive_tenant), avanzando el offset sin fila poison. Si lo estableces en cualquier valor distinto de default, debes confirmar que el productor emite ese mismo ce-tenantid; de lo contrario, el hub descarta el 100% del flujo y no entrega nada, sin ningún error. Un valor distinto del predeterminado emite una advertencia de arranque; hazle caso.

​
Análisis forense de la DLQ

GET /admin/dlq es la superficie forense del operador para las observaciones de dead-letter. Es cross-tenant por diseño: está protegida por el scope de admin de lib-auth, no lleva shim de tenant y devuelve registros de todos los tenants, así que no forma parte de la API /v1 orientada al cliente. Las observaciones de dead-letter que lee son solo de observabilidad: se capturan de los tópicos de dead-letter de los productores upstream y el hub nunca las reenvía. Úsala para investigar por qué fallaron los registros upstream; no los reproduce.

​
Reconciliador de tópicos

El reconciliador de tópicos es un detector de drift de solo lectura, habilitado por defecto (STREAMING_HUB_RECONCILER_ENABLED). En cada pasada compara los tópicos vivos del broker, el catálogo de eventos y los destinos de suscripción distintos, y señala tres tipos de drift: tópicos fantasma (un tópico seguido sin entrada en el catálogo), suscripciones muertas (un tipo de evento y major suscrito sin entrada viva en el catálogo) e infracciones de lag frente a retención. Detecta, nunca corrige: emite gauges de solo recuento y logs estructurados, y no escribe ningún estado del broker ni de la base de datos. Cuando está deshabilitado, no crea ninguna goroutine ni marca ningún cliente de admin, así que el camino deshabilitado no cuesta nada; deshabilitarlo pierde una alarma operativa pero nunca afecta la entrega.

​
Observabilidad

Streaming Hub exporta sus métricas, trazas y logs a través de OTLP (lib-observability), apuntando al colector en OTEL_EXPORTER_OTLP_ENDPOINT. Ahí es donde viven las métricas streaming_hub_* reales.
El endpoint /metrics está casi vacío por diseño: sirve solo el gauge estático streaming_hub_build_info. Haz scrape de las métricas reales del hub desde tu colector OTLP, no desde /metrics.
La identidad del tenant nunca es una etiqueta de métrica —vive en los atributos de span y en los campos de log—, así que la cardinalidad de las métricas se mantiene acotada sin importar cuántos tenants sirva un despliegue.

​
Próximos pasos

Cómo funciona Streaming Hub

Los detalles internos de entrega detrás de las superficies operativas de arriba.

Gestión de suscripciones

Las operaciones del plano de control que usan tus tenants.