Configuración de Fetcher

Las variables de entorno que definen un despliegue de Fetcher — cifrado, MongoDB, RabbitMQ, almacenamiento de objetos, multi-tenancy, telemetría y datasources internos.

Fetcher se configura por completo desde el entorno. Cada servicio lee su propio conjunto. El Manager y el Worker comparten la mayoría de las variables, y cada uno tiene algunas propias.

Para trabajo local, make set-env copia el .env.example de cada componente a .env. En producción, define las variables a través de tu orquestador.

Los dos servicios necesitan el mismo APP_ENC_KEY. El Worker lo usa para descifrar credenciales de datasource y para verificar la firma de cada mensaje que envía el Manager. Una clave ausente o corta detiene el proceso al arrancar. El log dice master key too short: got 0 bytes, minimum 32 required, y el servicio nunca abre un puerto.

​

Ambos servicios

---

​

Aplicación

Variable	Descripción	Por defecto	Obligatoria
APP_ENC_KEY	Clave maestra de 32 bytes codificada en base64. Genérala con make generate-master-key. Fetcher deriva de ella cuatro claves independientes.	—	Sí
APP_ENC_KEY_VERSION	Versión de clave registrada en cada credencial que Fetcher cifra. Increméntala cuando cambies la clave maestra.	1	No
ENV_NAME	Etiqueta del entorno. También selecciona el perfil del logger: production, staging, uat, development o local. Un valor ausente o desconocido selecciona el perfil local. El ejemplo que se distribuye define development.	—	No
LOG_LEVEL	Verbosidad del log. Si no la defines, sigue el perfil del entorno: debug para local y development, info para el resto.	—	No
VERSION	Cadena de versión que reporta /version. El ejemplo que se distribuye define v1.0.0.	0.0.0	No
DEPLOYMENT_MODE	saas, byoc o local. Etiqueta la respuesta de /readyz y activa la exigencia de TLS en SaaS. local además relaja la validación de licencia.	local	No
ALLOW_INSECURE_TLS	Permite conexiones en texto plano a MongoDB, Redis, PostgreSQL y RabbitMQ. Déjala sin definir en producción.	sin definir	No
READYZ_DRAIN_DELAY_SEC	Ventana de drenaje tras SIGTERM, en segundos. Mínimo 1.	12	No

​

MongoDB

MongoDB guarda los metadatos propios de Fetcher: registros de conexión y registros de job.

Variable	Descripción	Por defecto	Obligatoria
MONGO_URI	Esquema de conexión: mongodb o mongodb+srv. Fetcher compone la URI de conexión a partir de él. El ejemplo que se distribuye define mongodb.	—	Sí
MONGO_HOST	Host de MongoDB.	—	Sí
MONGO_PORT	Puerto de MongoDB.	—	Sí
MONGO_NAME	Nombre de la base de datos MongoDB. El acceso de repositorio resuelve este nombre en minúsculas.	—	Sí
MONGO_USER	Usuario de la base de datos.	—	Sí
MONGO_PASSWORD	Contraseña de la base de datos. Fetcher la escapa para la URL.	—	Sí
MONGO_PARAMETERS	Parámetros extra de query-string para la URI.	—	No
MONGO_TLS_CA_CERT	Certificado CA en PEM codificado en base64 para TLS.	—	No

​

RabbitMQ

Variable	Descripción	Por defecto	Obligatoria
RABBITMQ_URI	Esquema AMQP. Fetcher compone la URL del broker a partir de él. El ejemplo que se distribuye define amqp.	—	Sí
RABBITMQ_HOST	Host del broker.	—	Sí
RABBITMQ_PORT_AMQP	Puerto AMQP.	—	Sí
RABBITMQ_PORT_HOST	Puerto de gestión.	—	No
RABBITMQ_DEFAULT_USER	Usuario del broker.	—	Sí
RABBITMQ_DEFAULT_PASS	Contraseña del broker.	—	Sí
RABBITMQ_HEALTH_CHECK_URL	URL de gestión que llama la sonda de readiness. El ejemplo que se distribuye la construye con RABBITMQ_HOST y RABBITMQ_PORT_HOST.	—	No
RABBITMQ_FETCHER_WORK_QUEUE	Cola que lleva los jobs de extracción del Manager al Worker. Los dos servicios deben nombrar la misma cola. El ejemplo que se distribuye usa fetcher.extract-external-data.queue.	—	Sí
RABBITMQ_TLS	Activa TLS hacia el broker.	false	No

​

Multi-tenancy

Variable	Descripción	Por defecto	Obligatoria
MULTI_TENANT_ENABLED	Activa el aislamiento de una base de datos por tenant. También activa la guarda de seguridad sobre los hosts de datasource provistos por el tenant.	false	No
MULTI_TENANT_URL	URL del servicio Tenant Manager.	—	Con multi-tenancy
MULTI_TENANT_SERVICE_API_KEY	API key por defecto para las consultas al Tenant Manager.	—	Con multi-tenancy
MULTI_TENANT_SERVICE_API_KEY_<SERVICE>	Clave por servicio. El sufijo es el nombre del servicio en mayúsculas, con los guiones convertidos en guiones bajos (plugin-crm pasa a PLUGIN_CRM). Si falta, usa la clave por defecto.	—	No
MULTI_TENANT_REDIS_HOST	Host de Redis para el Pub/Sub de tenants.	—	Con multi-tenancy
MULTI_TENANT_REDIS_PORT	Puerto de Redis del Pub/Sub de tenants.	6379	No
MULTI_TENANT_REDIS_PASSWORD	Contraseña de Redis del Pub/Sub de tenants.	—	No
MULTI_TENANT_REDIS_TLS	TLS para el Redis del Pub/Sub de tenants. El cliente confía en el almacén de certificados del runtime, así que instala ahí tu CA privada.	false	No
MULTI_TENANT_MAX_TENANT_POOLS	Techo de pools de conexión concurrentes por tenant.	100	No
MULTI_TENANT_IDLE_TIMEOUT_SEC	Timeout de inactividad antes de liberar el pool de un tenant.	300	No
MULTI_TENANT_CACHE_TTL_SEC	TTL de la configuración de tenant en caché. El ejemplo que se distribuye define 120.	—	No
MULTI_TENANT_TIMEOUT	Timeout de las llamadas al Tenant Manager, en segundos.	30	No
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD	Fallos consecutivos antes de que abra el circuit breaker de tenants.	5	No
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC	Cuánto permanece abierto el breaker antes de un intento de reinicio.	30	No
MULTI_TENANT_ALLOW_INSECURE_HTTP	Permite HTTP en texto plano hacia el Tenant Manager.	false	No

Paradas de arranque en modo multi-tenant. MULTI_TENANT_ENABLED=true exige MULTI_TENANT_URL, MULTI_TENANT_SERVICE_API_KEY y MULTI_TENANT_REDIS_HOST. Un valor ausente aborta el arranque en ambos servicios, y el error nombra la variable. Dos variables MULTI_TENANT_SERVICE_API_KEY_<SERVICE> que se normalizan al mismo token también abortan el arranque, y el error nombra el token. La credencial de un servicio nunca sobrescribe en silencio la de otro.

​

Telemetría

Variable	Descripción	Por defecto	Obligatoria
ENABLE_TELEMETRY	Activa trazas y métricas de OpenTelemetry.	false	No
OTEL_EXPORTER_OTLP_ENDPOINT	Endpoint del colector OTLP.	—	Con telemetría
OTEL_INSECURE_EXPORTER	Permite una conexión del exportador en texto plano.	false	No
OTEL_RESOURCE_SERVICE_NAME	Nombre del servicio en la telemetría. Los ejemplos que se distribuyen definen fetcher para el Manager y fetcher-worker para el Worker.	—	No
OTEL_LIBRARY_NAME	Nombre de la librería de instrumentación. El ejemplo que se distribuye define github.com/LerianStudio/fetcher/v2.	—	No
OTEL_RESOURCE_SERVICE_VERSION	Atributo de versión del servicio. /readyz reporta este valor, y reporta unknown cuando está sin definir. El ejemplo que se distribuye lo apunta a VERSION.	—	No
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT	Atributo de entorno de despliegue. El ejemplo que se distribuye lo apunta a ENV_NAME.	—	No

​

Solo el Manager

---

Variable	Descripción	Por defecto	Obligatoria
SERVER_ADDRESS	Dirección de escucha de la API HTTP. El mismo listener sirve /health, /readyz, /metrics y /version. El ejemplo que se distribuye la construye a partir de SERVER_PORT, que define en 4006.	—	Sí
SWAGGER_ENABLED	Sirve la referencia de API en /swagger/docs y el contrato OpenAPI 3.1 en /swagger/openapi.json y /swagger/openapi.yaml.	false	No
PLUGIN_AUTH_ENABLED	Activa la autenticación con Access Manager. El modo multi-tenant la exige.	false	No
PLUGIN_AUTH_ADDRESS	Dirección de Access Manager.	—	Con autenticación
SCHEMA_CACHE_TTL_SECONDS	TTL del esquema de datasource en caché. Un valor vacío o inválido cae a 5 minutos.	300	No
REDIS_HOST	Host de Valkey o Redis. Respalda la caché de esquemas y el limitador de tasa de la prueba de conexión.	—	No
REDIS_PORT	Puerto de Redis.	—	No
REDIS_PASSWORD	Contraseña de Redis.	—	No
REDIS_DB	Índice de base de datos de Redis.	0	No
REDIS_TLS	Activa TLS hacia Redis.	false	No
REDIS_CA_CERT	CA en PEM codificada en base64, usada cuando REDIS_TLS=true.	—	No
MAX_PAGINATION_LIMIT	Techo del parámetro de consulta limit en cada operación de listado.	100	No
MAX_PAGINATION_MONTH_DATE_RANGE	Techo de la ventana de fecha de creación en cada operación de listado, en meses.	1	No

El router se niega a construirse ante dos incompatibilidades de seguridad. Reporta tenant middleware requires effective authentication cuando el modo multi-tenant corre con la autenticación desactivada. Reporta auth middleware is enabled but its address is empty cuando PLUGIN_AUTH_ENABLED=true y PLUGIN_AUTH_ADDRESS está vacío. En ambos casos el Manager no arranca.

​

Solo el Worker

---

​

Runtime y eventos

Variable	Descripción	Por defecto	Obligatoria
HEALTH_PORT	Puerto del microservidor de salud del Worker. Sirve /health, /readyz, /readyz/tenant/:id y /metrics. El Worker no tiene otro servidor HTTP.	4007	No
RABBITMQ_NUMBERS_OF_WORKERS	Cuántos jobs procesa el Worker en paralelo.	5	No
MONGO_MAX_POOL_SIZE	Tamaño del pool del cliente Mongo para el almacén de metadatos. El ejemplo que se distribuye define 1000.	100	No
STREAMING_ENABLED	Debe ser true. Los eventos terminales de job son un contrato del producto, así que el Worker se niega a arrancar sin streaming.	false	Sí
STREAMING_BROKERS	Lista de brokers bootstrap de la capa de streaming, como pares host:puerto separados por comas. El ejemplo que se distribuye define localhost:9092.	—	Sí
STREAMING_CLOUDEVENTS_SOURCE	Source de CloudEvents que se estampa en los eventos que emite el Worker. El ejemplo que se distribuye define //lerian.fetcher/worker.	—	Sí
STREAMING_CLIENT_ID	Identificador del cliente de streaming.	—	No
STREAMING_COMPRESSION	Códec de compresión: snappy, lz4, zstd, gzip o none.	lz4	No
STREAMING_REQUIRED_ACKS	Nivel de acuse del productor: all, leader o none.	all	No
RABBITMQ_JOB_EVENTS_EXCHANGE	Exchange que lleva job.completed y job.failed. El ejemplo que se distribuye usa fetcher.job.events.	—	Sí
MULTI_TENANT_RECONCILE_INTERVAL_SEC	Intervalo con el que el Worker reconcilia los consumidores por tenant contra los tenants activos.	60	No
ENGINE_MAX_RESULT_BYTES	Reemplaza el techo del resultado serializado del engine, como cantidad de bytes. Cero o negativo mantiene el valor por defecto.	268435456	No
CRYPTO_ENCRYPT_SECRET_KEY_PLUGIN_CRM	Clave de cifrado para el camino de extracción de compatibilidad con CRM.	—	No
CRYPTO_HASH_SECRET_KEY_PLUGIN_CRM	Clave de hash para el camino de extracción de compatibilidad con CRM.	—	No

El Worker falla cerrado ante la configuración de eventos. STREAMING_ENABLED sin definir o en false aborta el arranque con STREAMING_ENABLED=true is required for mandatory job event notifications. Un RABBITMQ_JOB_EVENTS_EXCHANGE vacío, un STREAMING_BROKERS vacío y un STREAMING_CLOUDEVENTS_SOURCE vacío abortan el arranque de la misma forma, igual que un STREAMING_COMPRESSION o un STREAMING_REQUIRED_ACKS fuera del conjunto aceptado. El Worker nunca cae a un emisor silencioso que no hace nada.

​

Almacenamiento de objetos

El Worker escribe cada resultado almacenado en almacenamiento de objetos compatible con S3. El esquema del endpoint controla TLS, así que http:// lo desactiva.

Variable	Descripción	Por defecto	Obligatoria
OBJECT_STORAGE_ENDPOINT	Endpoint compatible con S3, por ejemplo http://minio:9000. Déjalo sin definir para apuntar a AWS S3.	—	No
OBJECT_STORAGE_REGION	Región de S3.	us-east-1	No
OBJECT_STORAGE_BUCKET	Bucket para los resultados almacenados. El Worker no arranca sin él.	—	Sí
OBJECT_STORAGE_KEY_PREFIX	Prefijo de clave aplicado a los objetos almacenados.	—	No
OBJECT_STORAGE_ACCESS_KEY_ID	Access key ID estática. Defínela junto con OBJECT_STORAGE_SECRET_KEY, o deja ambas sin definir para usar la cadena de credenciales de AWS del entorno.	—	No
OBJECT_STORAGE_SECRET_KEY	Secret access key estática. Defínela junto con OBJECT_STORAGE_ACCESS_KEY_ID. Definir solo una de las dos aborta el arranque.	—	No
OBJECT_STORAGE_USE_PATH_STYLE	Direccionamiento path-style. Ponlo en true para MinIO y SeaweedFS.	false	No

Define la expiración de los resultados con una política de ciclo de vida en el bucket. Consulta Despliegue.

​

Compatibilidad de firma de mensajes

Variable	Descripción	Por defecto	Obligatoria
RABBITMQ_ALLOW_LEGACY_BODY_SIGNATURE_FALLBACK	Flag de compatibilidad para una actualización progresiva. También acepta firmas solo sobre el cuerpo en los mensajes consumidos. Una firma solo sobre el cuerpo no vincula el mensaje con su tenant, su job, su exchange ni su routing key. Se distribuye desactivado. Actívalo solo mientras avanzas una flota, y después desactívalo.	false	No

​

Datasources internos

---

Los datasources internos son las bases de datos de otros productos Lerian. Fetcher los resuelve sin una conexión registrada por API. Declaras cada uno con un grupo DATASOURCE_{NAME}_*, donde {NAME} es un prefijo que eliges tú.

Los valores aceptados en _CONFIG_NAME son un registro fijo: midaz_onboarding, midaz_transaction y plugin_crm. Fetcher omite cualquier otro nombre y registra una advertencia que nombra tanto el valor rechazado como el conjunto aceptado. Para tus propias bases de datos, registra una conexión a través de la API.

Variable	Descripción	Ejemplo
DATASOURCE_{NAME}_CONFIG_NAME	Nombre del datasource en el registro. Obligatorio.	midaz_onboarding
DATASOURCE_{NAME}_TYPE	Tipo de datasource, sin distinguir mayúsculas de minúsculas. Obligatorio.	POSTGRESQL
DATASOURCE_{NAME}_HOST	Host. Obligatorio.	db.internal.example.com
DATASOURCE_{NAME}_PORT	Puerto. Obligatorio.	5432
DATASOURCE_{NAME}_DATABASE	Nombre de la base de datos. Obligatorio.	onboarding
DATASOURCE_{NAME}_USER	Usuario.	fetcher_ro
DATASOURCE_{NAME}_PASSWORD	Contraseña. Provéela desde tu gestor de secretos.	—
DATASOURCE_{NAME}_SSLMODE	Modo TLS. Este es el control de TLS en este camino.	require
DATASOURCE_{NAME}_OPTIONS	Opciones de query-string. Solo MongoDB.	authSource=admin

Un valor incorrecto omite el datasource, y lo dice. Un _TYPE inválido, un _SSLMODE inválido, o un _HOST o _DATABASE ausente hacen que Fetcher omita ese datasource y registre una advertencia que nombra el config name y el valor ofensor. Fetcher nunca degrada una configuración TLS para alcanzar una base de datos.

​

Próximos pasos

---

Despliegue

Dependencias, colas, almacenamiento, escalado y verificaciones de arranque.

Seguridad

Clave maestra, claves derivadas, firma y validación de host.

Observabilidad

Sondas, comportamiento de drenaje, métricas y trazas.

Primeros pasos

Una primera extracción, con o sin infraestructura.