Referencia de configuración

Referencia de configuración del servicio Ledger

El servicio Ledger usa configuraciones de base de datos específicas por módulo:

ledger:
  enabled: true
  name: "ledger"
  replicaCount: 1

  image:
    repository: lerianstudio/midaz-ledger
    tag: ""  # Por defecto Chart.AppVersion
    pullPolicy: IfNotPresent

  configmap:
    # Configuración de la aplicación
    ENV_NAME: "production"
    LOG_LEVEL: "debug"
    SERVER_PORT: "3002"
    SERVER_ADDRESS: ":3002"

    # Configuración de autenticación
    PLUGIN_AUTH_ENABLED: "false"
    PLUGIN_AUTH_HOST: ""

    # Configuración de contabilidad
    # Administrado vía Ledger Settings API — ver PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings
    # Cuerpo de la solicitud: {"accounting": {"validateRoutes": true, "validateAccountType": true}}

    # PostgreSQL - Módulo Onboarding
    DB_ONBOARDING_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
    DB_ONBOARDING_USER: "midaz"
    DB_ONBOARDING_NAME: "onboarding"
    DB_ONBOARDING_PORT: "5432"
    DB_ONBOARDING_SSLMODE: "disable"
    DB_ONBOARDING_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

    # PostgreSQL - Módulo Transaction
    DB_TRANSACTION_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
    DB_TRANSACTION_USER: "midaz"
    DB_TRANSACTION_NAME: "transaction"
    DB_TRANSACTION_PORT: "5432"
    DB_TRANSACTION_SSLMODE: "disable"
    DB_TRANSACTION_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

    # MongoDB - Módulo Onboarding
    MONGO_ONBOARDING_HOST: "midaz-mongodb.midaz.svc.cluster.local."
    MONGO_ONBOARDING_NAME: "onboarding"
    MONGO_ONBOARDING_USER: "midaz"
    MONGO_ONBOARDING_PORT: "27017"

    # MongoDB - Módulo Transaction
    MONGO_TRANSACTION_HOST: "midaz-mongodb.midaz.svc.cluster.local."
    MONGO_TRANSACTION_NAME: "transaction"
    MONGO_TRANSACTION_USER: "midaz"
    MONGO_TRANSACTION_PORT: "27017"

    # Redis (compartido)
    REDIS_HOST: "midaz-valkey-primary.midaz.svc.cluster.local.:6379"

    # RabbitMQ (compartido)
    RABBITMQ_HOST: "midaz-rabbitmq.midaz.svc.cluster.local."
    # RABBITMQ_VHOST: "/"

    # Pools de conexión a base de datos
    # DB_ONBOARDING_MAX_OPEN_CONNS: ""
    # DB_ONBOARDING_MAX_IDLE_CONNS: ""
    # DB_TRANSACTION_MAX_OPEN_CONNS: ""
    # DB_TRANSACTION_MAX_IDLE_CONNS: ""

    # Balance Sync Worker
    BALANCE_SYNC_BATCH_SIZE: "100"
    BALANCE_SYNC_FLUSH_TIMEOUT_MS: "1000"
    BALANCE_SYNC_POLL_INTERVAL_MS: "500"

    # Multi-Tenant
    MULTI_TENANT_ENABLED: "false"
    # MULTI_TENANT_URL: "http://tenant-manager:4003"
    # MULTI_TENANT_SERVICE_API_KEY: ""
    # MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC: ""
    # MULTI_TENANT_CACHE_TTL_SEC: "120"
    # MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD: "5"
    # MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC: "30"
    # MULTI_TENANT_REDIS_HOST: ""
    # MULTI_TENANT_REDIS_PORT: "6379"
    # MULTI_TENANT_REDIS_PASSWORD: ""
    # MULTI_TENANT_REDIS_TLS: "false"

    # Multi-Tenant (solo CRM)
    # MULTI_TENANT_TIMEOUT: "30"
    # MULTI_TENANT_MAX_TENANT_POOLS: "100"
    # MULTI_TENANT_IDLE_TIMEOUT_SEC: "300"

    # Circuit Breaker de RabbitMQ
    RABBITMQ_CIRCUIT_BREAKER_CONSECUTIVE_FAILURES: "15"
    RABBITMQ_CIRCUIT_BREAKER_FAILURE_RATIO: "50"
    RABBITMQ_CIRCUIT_BREAKER_INTERVAL: "120"
    RABBITMQ_CIRCUIT_BREAKER_MAX_REQUESTS: "3"
    RABBITMQ_CIRCUIT_BREAKER_MIN_REQUESTS: "10"
    RABBITMQ_CIRCUIT_BREAKER_TIMEOUT: "30"
    RABBITMQ_CIRCUIT_BREAKER_HEALTH_CHECK_INTERVAL: "30"
    RABBITMQ_CIRCUIT_BREAKER_HEALTH_CHECK_TIMEOUT: "10"

    # Registro de auditoría
    AUDIT_LOG_ENABLED: "false"
    RABBITMQ_AUDIT_EXCHANGE: "audit.append_log.exchange"
    RABBITMQ_AUDIT_KEY: "audit.append_log.key"

    # Eventos de transacción
    RABBITMQ_TRANSACTION_EVENTS_ENABLED: "false"
    RABBITMQ_TRANSACTION_EVENTS_EXCHANGE: "transaction.transaction_events.exchange"

    # Paginación
    MAX_PAGINATION_MONTH_DATE_RANGE: "3"

  secrets:
    # Módulo Onboarding
    DB_ONBOARDING_PASSWORD: ""
    DB_ONBOARDING_REPLICA_PASSWORD: ""
    MONGO_ONBOARDING_PASSWORD: ""

    # Módulo Transaction
    DB_TRANSACTION_PASSWORD: ""
    DB_TRANSACTION_REPLICA_PASSWORD: ""
    MONGO_TRANSACTION_PASSWORD: ""

    # Compartidos
    REDIS_PASSWORD: ""
    RABBITMQ_DEFAULT_PASS: ""
    RABBITMQ_CONSUMER_PASS: ""

Soporte para secretos externos

ledger:
  useExistingSecret: true
  existingSecretName: <nombre-secreto-existente>

Referencia de flags de despliegue

Flag	Por defecto	Descripción
ledger.enabled	true	Habilita el servicio Ledger unificado
onboarding.enabled	—	Servicio dividido heredado — eliminado de las versiones actuales del chart (solo migración)
transaction.enabled	—	Servicio dividido heredado — eliminado de las versiones actuales del chart (solo migración)
migration.allowAllServices	false	Flag oculto para permitir todos los servicios simultáneamente

Referencia de variables de entorno

Descripciones detalladas para las variables que no son auto-explicativas a partir del bloque YAML anterior.

Pools de conexión a base de datos

Variable	Descripción	Predeterminado
`DB_ONBOARDING_MAX_OPEN_CONNS`	Máximo de conexiones abiertas a la base de datos PostgreSQL de Onboarding.	Valor por defecto de Go (ilimitado)
`DB_ONBOARDING_MAX_IDLE_CONNS`	Máximo de conexiones inactivas mantenidas vivas para la base de datos de Onboarding.	Valor por defecto de Go (2)
`DB_TRANSACTION_MAX_OPEN_CONNS`	Máximo de conexiones abiertas a la base de datos PostgreSQL de Transaction.	Valor por defecto de Go (ilimitado)
`DB_TRANSACTION_MAX_IDLE_CONNS`	Máximo de conexiones inactivas mantenidas vivas para la base de datos de Transaction.	Valor por defecto de Go (2)

Para cargas de trabajo en producción, establece límites explícitos de pool para prevenir el agotamiento de conexiones. Un punto de partida común: MAX_OPEN_CONNS=25, MAX_IDLE_CONNS=10 por módulo de base de datos. Ajusta según tu configuración max_connections de PostgreSQL y el número de réplicas de Midaz.

RabbitMQ

Variable	Descripción	Predeterminado
`RABBITMQ_VHOST`	Virtual host de RabbitMQ. Útil para aislar el tráfico de Midaz en clústeres de RabbitMQ compartidos.	`/`

Registro de auditoría

Cuando está habilitado, Midaz publica registros de auditoría detallados a nivel de operación en un exchange de RabbitMQ después de cada transacción. El payload de auditoría incluye los datos completos de la operación (montos, cuentas, saldos antes/después) serializados como JSON. Consumes estos eventos vinculando tu propia cola al exchange de auditoría.

Variable	Descripción	Predeterminado
`AUDIT_LOG_ENABLED`	Habilita el registro de auditoría de transacciones.	`false`
`RABBITMQ_AUDIT_EXCHANGE`	Nombre del exchange de RabbitMQ para los mensajes de auditoría.	`audit.append_log.exchange`
`RABBITMQ_AUDIT_KEY`	Routing key para los mensajes de auditoría.	`audit.append_log.key`

Eventos de transacción

Variable	Descripción	Predeterminado
`RABBITMQ_TRANSACTION_EVENTS_ENABLED`	Habilita la publicación de eventos de transacción en tiempo real. Consulta Event publisher para más detalles.	`false`
`RABBITMQ_TRANSACTION_EVENTS_EXCHANGE`	Nombre del exchange de RabbitMQ para los eventos de transacción.	`transaction.transaction_events.exchange`

Procesamiento asíncrono de transacciones

Cuando RABBITMQ_TRANSACTION_ASYNC está habilitado, Midaz procesa las transacciones de forma asíncrona a través de consumidores RabbitMQ, en lugar de hacerlo de forma inline durante la solicitud a la API. El bulk recorder agrupa adicionalmente las escrituras a la base de datos para mayor rendimiento.

Las variables BULK_RECORDER_* solo tienen efecto cuando ambas RABBITMQ_TRANSACTION_ASYNC=true y BULK_RECORDER_ENABLED=true están activas.

Variable	Descripción	Predeterminado
`RABBITMQ_TRANSACTION_ASYNC`	Habilita el procesamiento asíncrono de transacciones mediante consumidores RabbitMQ.	`false`
`RABBITMQ_NUMBERS_OF_WORKERS`	Número de goroutines de workers consumidores asíncronos.	`5`
`RABBITMQ_NUMBERS_OF_PREFETCH`	Conteo de prefetch de RabbitMQ por worker — controla cuántos mensajes almacena en buffer cada worker a la vez.	`10`
`BULK_RECORDER_ENABLED`	Habilita el modo de inserción masiva para escrituras de operaciones cuando el procesamiento asíncrono está activo.	`true`
`BULK_RECORDER_SIZE`	Tamaño del lote para inserciones masivas. Configura en `0` para dimensionamiento automático según la carga.	`0` (auto)
`BULK_RECORDER_FLUSH_TIMEOUT_MS`	Tiempo máximo (en milisegundos) para esperar antes de vaciar un lote incompleto.	—
`BULK_RECORDER_MAX_ROWS_PER_INSERT`	Número máximo de filas por sentencia INSERT durante escrituras masivas.	—

Paginación

Variable	Descripción	Predeterminado
`MAX_PAGINATION_MONTH_DATE_RANGE`	Rango máximo de fechas (en meses) permitido para las consultas paginadas. Limita qué tan atrás los endpoints de listado pueden consultar. Usa `0` para rango ilimitado.	`3`
`MAX_PAGINATION_LIMIT`	Número máximo de elementos devueltos por página en las respuestas paginadas de la API.	`100`

El límite del rango de fechas de paginación previene escaneos completos de tabla costosos en conjuntos de datos grandes. Si tu caso de uso requiere consultar datos históricos más allá de 3 meses, aumenta este valor o configúralo en 0 — pero monitorea el rendimiento de las consultas en consecuencia.