RUN_MODE selecciona qué superficies sirve un proceso. La misma imagen se ejecuta como la API, como el worker de informes o como ambas. Detrás de ellas hay cuatro dependencias.
Reporter lee tus bases de datos mediante un motor de extracción que se ejecuta dentro del proceso worker. No hay un servicio de extracción separado que desplegar.
Qué despliegas
Modos de ejecución
RUN_MODE=api sirve todas las operaciones REST, además de /health, /readyz y /version, en la dirección de SERVER_ADDRESS. RUN_MODE=worker consume la cola de comandos de informes y sirve /health y /readyz en HEALTH_PORT. RUN_MODE=all ejecuta ambas superficies en un solo proceso.
Usa all para el desarrollo local. En producción, despliega las dos superficies por separado, de modo que la generación de informes escale por su cuenta.
MongoDB
Ambas superficies usan el mismo despliegue de MongoDB. La superficie de la API escribe plantillas, informes y plazos. El worker actualiza un informe a medida que se completa.
MONGO_HOST y MONGO_NAME son obligatorias al iniciar cuando MULTI_TENANT_ENABLED es false, el valor predeterminado.
RabbitMQ
Dos responsabilidades separadas comparten un broker.
La cola de comandos de informes
Esta cola lleva el trabajo desde la superficie de la API hasta el worker.RABBITMQ_EXCHANGE, RABBITMQ_GENERATE_REPORT_QUEUE y RABBITMQ_GENERATE_REPORT_KEY nombran el exchange, la cola y la routing key. La superficie de la API publica, así que necesita las tres, además de su conexión al broker: RABBITMQ_HOST, RABBITMQ_PORT_AMQP, RABBITMQ_DEFAULT_USER y RABBITMQ_DEFAULT_PASS. El worker consume de la cola y necesita esa misma conexión, además de RABBITMQ_GENERATE_REPORT_QUEUE. Los objetos del broker deben existir antes de que cualquiera de los dos servicios inicie.
El canal es interno de Reporter. Para saber que un informe terminó, suscríbete a los eventos de negocio de más abajo, o consulta el informe periódicamente.
Un worker que falla al procesar un mensaje lo reintenta hasta cinco veces con backoff, y luego lo rechaza sin volver a encolarlo. Vincula un dead-letter exchange a la cola de comandos, de modo que un informe rechazado llegue a un lugar donde puedas inspeccionarlo.
El exchange de eventos
Los eventos de negocio (template.*, report.*, deadline.*, regulatory.*) van a un exchange que nombras en RABBITMQ_REPORT_EVENTS_EXCHANGE. El valor lo configura el operador. El valor de referencia es reporter.events.
Configura ese exchange, STREAMING_BROKERS y STREAMING_CLOUDEVENTS_SOURCE siempre que STREAMING_ENABLED=true. Con el streaming apagado, ambas superficies inician con normalidad y no publican nada.
Almacenamiento de objetos
Reporter usa un bucket compatible con S3, nombrado en
OBJECT_STORAGE_BUCKET. Contiene dos tipos de objeto, cada uno bajo su propio prefijo:
- la fuente de la plantilla, como
templates/<templateId>.tpl - el informe renderizado, como
reports/<templateId>/<reportId>.<format>
OBJECT_STORAGE_USE_PATH_STYLE=true es lo que esperan MinIO y SeaweedFS, y OBJECT_STORAGE_DISABLE_SSL permanece en false fuera del desarrollo local.
Retención de informes
Reporter conserva para siempre los archivos de informes y las presentaciones regulatorias. No tiene un endpoint de eliminación ni una configuración de retención, así que el bucket crece con tu volumen de informes. La única forma de que un archivo expire es una regla de ciclo de vida del almacén de objetos que tú configuras. Esa regla también elimina las presentaciones regulatorias aprobadas, que son el registro regulatorio de la institución. Las filas guardadas a partir de las cuales una corrección regulatoria vuelve a generar el borrador también se almacenan enreports/, así que una regla de expiración puede impedir que se corrija un borrador más antiguo.
Redis o Valkey
REDIS_HOST es obligatoria en la superficie de la API. Redis respalda el bloqueo de idempotencia en la creación de informes y la caché de esquemas de las fuentes de datos.
El estado de idempotencia vive en Redis, no en la memoria del proceso, así que las réplicas de la API lo comparten.
Fuentes de datos
Reporter lee los datos de generación de informes desde fuentes de datos de PostgreSQL y MongoDB en su registro persistido. Créalas y adminístralas mediante la API de fuentes de datos. Un bloque opcional
DATASOURCE_{NAME}_* siembra una entrada de registro administrada por el usuario al iniciar el Manager. Siembra la entrada solo cuando ese configName está ausente. Las ediciones y eliminaciones posteriores por la API tienen precedencia sobre el entorno.
Tanto el Manager como el worker requieren la misma DATASOURCE_CRED_ENC_KEY persistente para proteger las credenciales del registro. Mantenla sin cambios a través de reinicios y despliegues, para que puedan seguir descifrando las credenciales almacenadas. Reporter también inicia sin ninguna configurada, y sirve plantillas, plazos y métricas.
Dimensionamiento del worker
RABBITMQ_NUMBERS_OF_WORKERS establece cuántos trabajos de informes ejecuta en paralelo un proceso worker. Para escalar horizontalmente, agrega réplicas de worker y dirígelas según la profundidad de la cola de comandos.
La salida en PDF se renderiza mediante un pool de navegadores headless: PDF_POOL_WORKERS renderizados concurrentes, que por defecto es 2, cada uno acotado por PDF_TIMEOUT_SECONDS, que por defecto es 90. Dimensiona la memoria del worker según ese pool, no solo según las filas que lee un informe. Los demás formatos de salida no lo usan.
Cada extracción de una fuente de datos también lleva límites. Son 20 tablas por fuente de datos y 50 campos por tabla. También cubren un plazo de 300 segundos y un tope de 256 MiB en los datos extraídos. Las variables ENGINE_* los cambian. Cada tabla también devuelve como máximo 150.000 filas y cada consulta agota su tiempo tras 300 segundos, salvo que la fuente de datos defina sus propios valores.
Modo de despliegue y TLS
DEPLOYMENT_MODE declara el tipo de despliegue: local, byoc o saas. Etiqueta la respuesta de /readyz, y en saas exige TLS.
Deja ALLOW_INSECURE_TLS sin configurar en producción. Omite esas verificaciones, y el stack de desarrollo local es el único lugar donde corresponde usarla.
Verificaciones de inicio
Reporter valida su configuración antes de servir cualquier cosa. Cada verificación de abajo detiene el proceso, y el error nombra cada variable responsable.
Una dependencia caída al arrancar no produce un pod silenciosamente roto.
/health responde 503 hasta que la autosonda de inicio se completa correctamente. El kubelet entonces reinicia el pod en lugar de enviarle tráfico.Actualizaciones continuas
Al recibir
SIGTERM, ambas superficies entran en un drenaje. La sonda /readyz responde 503 desde el momento en que llega la señal, antes de que los servidores empiecen a apagarse. Las solicitudes y los mensajes en curso terminan. Kubernetes elimina el pod de los endpoints del Service mientras todavía funciona.
Configura el período de gracia de terminación por encima de tu renderizado de informe más largo. Consulta la referencia de salud y readiness para saber qué reportan las sondas durante un drenaje.
Próximos pasos
Variables de entorno
Todas las variables de Reporter, por categoría.
Configuración de BYOC
Los bloques de configuración que comparten todos los productos de Lerian.
Salud y readiness
El contrato de las sondas y qué significa cada respuesta.
Conectar Reporter con Midaz
Apunta Reporter a una base de datos de Midaz y renderiza tu primer informe.