Skip to main content
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_*, además de las variables compartidas MULTI_TENANT_*, PLUGIN_AUTH_* y OTEL_*, y de ENV_NAME sin prefijo. El inventario completo, con cada valor por defecto, está en la referencia de entorno del servicio. Las variables que estableces con más frecuencia: Eliminar una URL de STREAMING_HUB_MANIFEST_SOURCES detiene las actualizaciones futuras de ese productor, pero conserva sus últimas entradas válidas en el catálogo. La actualización de manifiestos solo sirve para el descubrimiento del plano de control; una caída del productor no bloquea la ingesta de eventos ni la coincidencia de entregas. Los valores de los secretos nunca pertenecen a la configuración versionada. 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. El material SASL y TLS de Kafka a nivel de despliegue, la API key de Tenant Manager y las credenciales de Redis deben provenir de tu almacén de secretos. Las credenciales M2M por tenant para descubrir manifests de productores permanecen en Secrets Manager.
STREAMING_HUB_TENANT_ID define el tenant del plano de control BYOC. La ingesta acepta cualquier ce-tenantid no vacío; un tenant distinto se persiste, pero no puede coincidir con suscripciones de este tenant BYOC. Si defines otro valor, las suscripciones deben usar ese tenant; de lo contrario, la ingesta funciona, pero la entrega queda vacía. 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.