Variables de entorno de Plugin SISBAJUD

Variables de entorno de Plugin SISBAJUD: runtime, autenticación, licencia, gestión de claves, conexión con la Mensageria, tiempos de ejecución, listener de webhook, Midaz y streaming de eventos.

Esta página lista las variables de entorno del Plugin SISBAJUD. Variables de entorno de la Lerian SISBAJUD Mensageria lista las variables de la Mensageria. Fundamentos de configuración de BYOC documenta las variables que comparte cada servicio Go de Lerian: servidor, almacenes de datos, telemetría y autenticación de plugins.

En las tablas siguientes, la columna Predeterminado / Obligatorio muestra el valor predeterminado. Un calificador en negrita (por ejemplo, Obligatorio) marca las variables que debes configurar. — significa que no hay valor predeterminado. Una variable marcada como Sensible guarda una credencial o material de claves. Inyéctala desde tu gestor de secretos en el momento del despliegue. No hagas commit de su valor.

El plugin solo arranca en modo ejecutor, y solo para un tenant. EXECUTOR_ENABLED=true activa el modo ejecutor. Con EXECUTOR_ENABLED en blanco, una MENSAGERIA_BASE_URL no vacía también lo activa, y false no desactiva el plugin de una Mensageria configurada. Sin ninguno de los dos, el plugin se niega a arrancar. Con MULTI_TENANT_ENABLED=true, también se niega a arrancar. Con EXECUTOR_ENABLED=true y sin MENSAGERIA_BASE_URL, el plugin corre sin la Mensageria, solo para el canal directo. En ese caso exige MIDAZ_BASE_URL, EXECUTOR_M2M_SUBJECT, RESPONSE_DEADLINE_MARGIN y EXECUTOR_HEARTBEAT_EVERY. No lee las variables de cliente, mTLS ni de listener de webhook de la Mensageria, excepto EXECUTOR_HUB_WEBHOOK_MAX_HANDLE_ATTEMPTS, que limita los intentos de cada orden directa.

Para instalar o actualizar el plugin, consulta el README del chart.

​

Servicio y runtime

Variable	Predeterminado / Obligatorio	Descripción
SERVER_ADDRESS	Configúrala como :4029	Dirección de escucha de la API principal. La imagen expone el puerto 4029. El puerto de la API principal se abre cuando PostgreSQL responde. Entre las sondas, este puerto sirve solo /health y /version.
HEALTH_PORT	—	Puerto del listener de salud, por ejemplo 8099. Sirve /health, /readyz y /metrics. Sin HEALTH_PORT, no arranca ningún listener de salud.
ENVIRONMENT_NAME	—	Entorno de ejecución. local, development, staging, e2e y test son valores de no producción. Cualquier otro valor, y ningún valor, ejecuta las verificaciones de producción.
DEPLOYMENT_MODE	local	local, byoc o saas. Con saas, el arranque rechaza una conexión PostgreSQL o Redis sin TLS. Fuera de local, el listener de webhook necesita TLS.
DEFAULT_TENANT_ID	11111111-1111-1111-1111-111111111111	Tenant de un despliegue single-tenant. Debe ser un UUID.
EXECUTOR_ENABLED	—	true o false. Cualquier otro valor rechaza el arranque.
SYSTEMPLANE_ENABLED	false	Sirve la API de administración de Systemplane en /system y los documentos de rutas contables en /tenant-system.

Las verificaciones de producción exigen POSTGRES_PASSWORD y rechazan POSTGRES_SSLMODE=disable. Con STREAMING_ENABLED=true, también exigen STREAMING_TLS_ENABLED=true.

​

Autenticación

Variable	Predeterminado / Obligatorio	Descripción
PLUGIN_AUTH_ENABLED	false	Verifica los bearer tokens de la API principal con el Access Manager. Con false, el plugin no sirve la resolución de decisión humana, el rearme de resultado, la resolución de intento estacionado, el borrado de órdenes directas ni la previsualización de la depuración, y el canal directo responde 501.
PLUGIN_AUTH_HOST	Obligatorio	Dirección del Access Manager. El plugin obtiene su token para la Mensageria en esta dirección, también cuando PLUGIN_AUTH_ENABLED es false.

​

Licencia

License Manager describe cómo el producto verifica la licencia.

Variable	Predeterminado / Obligatorio	Descripción
LICENSE_KEY	Obligatorio, a menos que LICENSE_FILE_PATH esté configurada	La clave de licencia que Lerian emitió para Plugin SISBAJUD. El plugin obtiene con ella un archivo de licencia firmado y lo mantiene en memoria. El arranque rechaza una clave vacía cuando LICENSE_FILE_PATH está vacía. La licencia es global, así que ninguna otra variable define su alcance.
LICENSE_FILE_PATH	—	Ruta de un archivo de licencia firmado que Lerian emite. Cuando está configurada, el plugin usa el archivo e ignora LICENSE_KEY, y un archivo que el plugin rechaza detiene el arranque.

Con LICENSE_KEY, un servicio de licencias que no responde no detiene el plugin: sigue activo, sin quedar listo, y reintenta. El plugin inicia el listener de webhook y su trabajo en segundo plano después de aceptar una licencia.

​

Gestión de claves

Variable	Predeterminado / Obligatorio	Descripción
KMS_PROVIDER	Obligatorio cuando ENVIRONMENT_NAME es production	Gestor de claves: vault (HashiCorp Vault Transit) o aws (AWS KMS). Cualquier otro valor rechaza el arranque. Con cualquier otro entorno, un valor no configurado significa vault.
AWS_REGION	Obligatorio con aws	Región de AWS KMS.
KMS_AWS_KEY_MODE	Obligatorio con aws	managed o provided. No tiene valor predeterminado. Cualquier otro valor rechaza el arranque.
KMS_AWS_KEY_ARN	Obligatorio con provided	ARN de tu clave de AWS KMS para los datos de la institución, en la región de AWS_REGION. Un ARN de alias rechaza el arranque. Con managed, déjala vacía.
KMS_AWS_CREDENTIALS_KEY_ARN	Obligatorio con provided	ARN de una segunda clave de AWS KMS, con las mismas reglas. Debe ser una clave distinta de KMS_AWS_KEY_ARN.
KMS_AWS_ROTATION_CHECK_INTERVAL_SEC	3600	Con provided, el intervalo, en segundos, en el que el plugin busca una rotación de tus claves. De 1 a 86400.
KMS_AWS_TIMEOUT_SEC	20	Timeout de cada llamada a AWS KMS, en segundos. De 1 a 600.
VAULT_ADDR	Obligatorio con vault	Dirección de tu Vault.
VAULT_AUTH_METHOD	token	token o approle. Cualquier otro valor rechaza el arranque.
VAULT_TOKEN	Obligatorio para token cuando ENVIRONMENT_NAME es production	Token de Vault. Sensible.
VAULT_APPROLE_ROLE_ID	Obligatorio para approle	Role ID de AppRole. Sensible.
VAULT_APPROLE_SECRET_ID	Obligatorio para approle	Secret ID de AppRole. Sensible.
VAULT_TRANSIT_MOUNT_PATH	transit	Ruta de montaje del motor Transit.
VAULT_TIMEOUT_SEC	15	Timeout de cada solicitud a Vault, en segundos. De 1 a 600.
VAULT_TOKEN_RENEW_ENABLED	true	Renueva el token de Vault en segundo plano.
VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC	60	Tiempo mínimo entre dos renovaciones, en segundos.

Con AWS KMS, los dos modos de clave son:

• managed. El plugin crea la clave de los datos de cada institución.
• provided. Tú creas las dos claves. El plugin nunca las crea ni las rota. Cuando el custodio de tus claves rota una clave, el plugin registra la nueva versión.

Los requisitos de la clave, las credenciales de AWS, los permisos, excepto kms:ListAliases, y el contexto de cifrado son los mismos que en la Mensageria. AWS KMS en la Mensageria los enumera. Elige el proveedor de claves una sola vez. Cuando la base de datos contiene datos que otro proveedor de claves protege, el arranque rechaza.

​

Conexión con la Mensageria

El plugin llama a la API de ejecución de la Mensageria. Integración con Lerian SISBAJUD la describe.

Variable	Predeterminado / Obligatorio	Descripción
MENSAGERIA_BASE_URL	Obligatorio con la Mensageria	URL base de la API de ejecución de la Mensageria (SISBAJUD_EXECUTION_ADDRESS en la Mensageria). Debe ser una URL https con host.
MENSAGERIA_MTLS_ENABLED	false	true presenta un certificado de cliente. false usa TLS unidireccional. Cualquier otro valor rechaza el arranque.
MENSAGERIA_TLS_CA_FILE	Obligatorio si MENSAGERIA_MTLS_ENABLED=true	Paquete de CA que verifica la Mensageria. Con TLS unidireccional, es opcional, y un valor vacío usa el almacén de confianza del sistema.
MENSAGERIA_TLS_CLIENT_CERT_FILE	Obligatorio si MENSAGERIA_MTLS_ENABLED=true	Certificado de cliente del plugin.
MENSAGERIA_TLS_CLIENT_KEY_FILE	Obligatorio si MENSAGERIA_MTLS_ENABLED=true	Clave privada de ese certificado. Sensible.
EXECUTOR_M2M_SUBJECT	Obligatorio	El sub del token M2M del plugin. El plugin lo registra como dueño de cada institución que crea.
MENSAGERIA_CLIENT_ID	Obligatorio	Client ID del cliente M2M del plugin.
MENSAGERIA_CLIENT_SECRET	Obligatorio	Client secret de ese cliente. Sensible. El arranque rechaza un par con solo uno de los dos valores.
STREAMING_HUB_TENANT_ID	Obligatorio	Tenant de las sondas canario.

​

Tiempos de ejecución

Variable	Predeterminado / Obligatorio	Descripción
EXECUTOR_TICK_EVERY	30s	Intervalo del ciclo de ejecución. Duración Go mayor que 0.
EXECUTOR_HEARTBEAT_EVERY	Obligatorio	Intervalo de los heartbeats de una escritura cuyo resultado no se conoce. Duración Go mayor que 0.
EXECUTOR_HUMAN_DECISION_AFTER_BEATS	3	Número de heartbeats sin cambio antes de que la orden pase a una decisión humana.
EXECUTOR_RESULT_MAX_ATTEMPTS	12	Número de envíos fallidos de un resultado antes de que el plugin lo estacione, registre una decisión humana y dispare una alarma. 0 significa el valor predeterminado. Un valor negativo rechaza el arranque. Un administrador de la plataforma rearma un resultado estacionado.
RESPONSE_DEADLINE_MARGIN	Obligatorio	Duración Go mayor que 0, por ejemplo 2h. Antes del plazo de la orden, el plugin mantiene este margen y entrega una escritura no resuelta a una decisión humana.
EXECUTOR_SETTLE_WINDOW	1s	Duración Go. Configúrala con al menos la latencia asíncrona de tu ledger.
EXECUTOR_ORPHAN_RECONCILE_WINDOW	48h	Hasta cuándo, en el pasado, el plugin busca operaciones en cuentas de bloqueo que no escribió.

​

Listener de webhook

Variable	Predeterminado / Obligatorio	Descripción
EXECUTOR_TRANSPORT	webhook	Cómo llegan los avisos de ejecución al plugin. Esta página describe webhook.
EXECUTOR_HUB_WEBHOOK_ADDRESS	:9082	Dirección de escucha del listener de webhook.
EXECUTOR_HUB_WEBHOOK_PATH	/v1/webhooks/hub	Ruta del listener de webhook. Debe empezar con /.
EXECUTOR_HUB_WEBHOOK_SECRET	Obligatorio	Secret de firma de la suscripción del Streaming Hub. Sensible.
EXECUTOR_HUB_WEBHOOK_SECRET_PREVIOUS	—	El secret anterior a la última rotación. El listener acepta los dos secrets. Sensible.
EXECUTOR_HUB_WEBHOOK_MAX_SKEW_SEC	300	De 1 a 300. El listener acepta una entrega fuera de esta diferencia de reloj, con una advertencia en el log.
EXECUTOR_HUB_WEBHOOK_TLS_CERT_FILE	Obligatorio fuera de DEPLOYMENT_MODE=local, salvo que el TLS termine antes	Certificado de servidor del listener. Configúralo junto con la clave.
EXECUTOR_HUB_WEBHOOK_TLS_KEY_FILE	Obligatorio con el certificado	Clave privada de ese certificado. Sensible.
EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED	false	Configúrala como true cuando el TLS termina delante del listener.
EXECUTOR_HUB_WEBHOOK_MAX_HANDLE_ATTEMPTS	5	Número de intentos para cada entrega aceptada. Debe ser al menos 1 + EXECUTOR_SETTLE_WINDOW / EXECUTOR_TICK_EVERY, redondeado hacia arriba.

​

Canal directo

El canal directo exige PLUGIN_AUTH_ENABLED activado, un tenant y el modo executor. Cómo Plugin SISBAJUD ejecuta órdenes lo describe.

Variable	Predeterminado / Obligatorio	Descripción
DIRECT_PERMANENT_BLOCK_ENABLED	false	true o false. Cualquier otro valor rechaza el arranque. Con false, el canal rechaza un nuevo bloqueo permanente con SBJ-0027. Con false, los bloqueos permanentes activos siguen bloqueando nuevos créditos hasta que se cierren. Con true, el plugin acepta un nuevo bloqueo permanente, y el arranque exige STREAMING_ENABLED true y STREAMING_BROKERS. STREAMING_BROKERS debe llegar a los brokers donde Midaz publica sus eventos de ledger: sin ellos, el plugin no captura ningún crédito posterior.
DIRECT_PERMANENT_REFRESH_EVERY	15m	Cada cuánto el plugin actualiza las cuentas del sujeto de un bloqueo permanente. De 1m a 15m.
EXECUTOR_PERMANENT_RESULT_EMITTER_ENABLED	false	true o false. Con true, el plugin escribe un resultado por cada bloqueo posterior de un bloqueo permanente. Exige DIRECT_PERMANENT_BLOCK_ENABLED true. El plugin retiene un resultado y dispara una alarma cuando connectorMetadata.permanentProducts no mapea el tipo de cuenta.
EXECUTOR_ORDER_SWEEP_ENABLED	false	true o false. Con true, el plugin cierra las revisiones terminadas de los dos canales.
EXECUTOR_DIRECT_DRAINER_INFRA_ALARM_THRESHOLD	3	El plugin dispara una alarma cuando una orden directa llega a cada múltiplo de este número de errores de infraestructura consecutivos. Al menos 1.
EXECUTOR_DIRECT_PURGE_ELIGIBLE_ALARM_AFTER	168h	Go duration mayor que 0. El plugin registra un error en el log cuando la orden directa más antigua que se puede borrar espera este tiempo, para que un administrador la revise. Un valor inválido detiene el plugin al iniciar.
EXECUTOR_DIRECT_PURGE_REFRESH_EVERY	15m	Go duration mayor que 0. Cada cuánto cuenta el plugin las órdenes directas que se pueden borrar. Un valor inválido detiene el plugin al iniciar.

​

Midaz

El plugin toma una conexión con Midaz para toda la instalación de estas variables. El plugin no guarda ninguna credencial de Midaz por institución, y la configuración de una institución informa connectionSource env. Operar Plugin SISBAJUD describe la configuración de la institución.

Variable	Predeterminado / Obligatorio	Descripción
MIDAZ_BASE_URL	Obligatorio	URL base del ledger Midaz. El plugin no arranca sin ella. Debe ser una URL https, salvo hacia un host de loopback o fuera de producción. Con el CRM embedded, el plugin también lee el CRM por esta dirección.
MIDAZ_AUTH_ADDRESS	—	Dirección del Access Manager que emite el token de Midaz. Configúrala junto con MIDAZ_LEDGER_CLIENT_ID y MIDAZ_LEDGER_CLIENT_SECRET, o no configures ninguna de las tres. Sin ninguna, el plugin no envía el header Authorization a Midaz. El plugin obtiene el token en {MIDAZ_AUTH_ADDRESS}/v1/login/oauth/access_token.
MIDAZ_LEDGER_CLIENT_ID	—	Client ID que el plugin usa para el ledger Midaz.
MIDAZ_LEDGER_CLIENT_SECRET	—	Client secret de ese client. Sensible.
MIDAZ_CRM_MODE	legacy	Superficie de CRM de las instituciones que no definen crmMode. Define embedded: el plugin lee el CRM del ledger Midaz en MIDAZ_BASE_URL.

Después de que una institución recibe su primera orden, el plugin no arranca si MIDAZ_BASE_URL apunta a otro Midaz distinto del que el plugin registró para esa institución. Lo mismo vale cuando el organizationId o el ledgerId de su executorLedger difiere del registro.

​

Streaming de eventos

Variable	Predeterminado / Obligatorio	Descripción
STREAMING_ENABLED	true	Publica eventos. El arranque rechaza false cuando STREAMING_BROKERS está configurada.
STREAMING_BROKERS	—	Lista de brokers Kafka separada por comas.
STREAMING_TLS_ENABLED	true en producción	Se conecta a los brokers por TLS.
OUTBOX_ENABLED	true	Ruta de entrega duradera de los eventos. STREAMING_ENABLED=true la exige.

​

Valores que deben coincidir con la Mensageria

• RESPONSE_DEADLINE_MARGIN. La Mensageria lee la misma variable. Configura el mismo valor en la Mensageria y en el Plugin SISBAJUD.
• TLS mutuo. Configura MENSAGERIA_MTLS_ENABLED con el mismo valor que SISBAJUD_EXECUTION_MTLS_ENABLED en la Mensageria. Con TLS mutuo activo en la Mensageria e inactivo en el plugin, el handshake TLS falla.
• Identidad del plugin. EXECUTOR_M2M_SUBJECT es el sub del token del cliente M2M en MENSAGERIA_CLIENT_ID.