Aspectos esenciales de la configuración de BYOC

Variables de entorno que se repiten entre los servicios de Lerian en Go al ejecutar BYOC en tu propia nube o on-premise.

En un despliegue BYOC (bring your own cloud), ejecutas los productos de Lerian dentro de tu propia infraestructura de AWS, GCP u on-premise. Tú eres dueño de los datos y del runtime. Configuras cada servicio mediante variables de entorno, y la mayoría son específicas del servicio. Esta página cubre variables que se repiten entre los servicios de Lerian en Go. Usa la página propia de cada producto para el resto.

Estas variables no son la lista completa. Los nombres y los valores predeterminados de las variables difieren entre servicios, y los servicios agregan sus propias claves. Consulta Variables por producto.

​

Modo de despliegue y TLS

Variable	Descripción	Predeterminado	Valores permitidos
DEPLOYMENT_MODE	Postura de despliegue. Su efecto, su valor predeterminado y los valores aceptados varían según el servicio.	Varía según el servicio	Varía según el servicio
ALLOW_INSECURE_TLS	Omite la exigencia de TLS por conexión en los DSN de infraestructura. Pensado solo para desarrollo local. Pix JD también la usa para aceptar direcciones http:// en sus conexiones salientes, en todo entorno.	false	true, false

Para un despliegue BYOC en producción, configura DEPLOYMENT_MODE=byoc, conecta cada almacén de datos por TLS y deja ALLOW_INSECURE_TLS sin definir (false).

​

Servidor

Variable	Descripción	Predeterminado	Valores permitidos
SERVER_ADDRESS	Dirección de escucha HTTP principal (host:port, normalmente :port). La ubicación de las sondas depende de la release del servicio.	Varía según el servicio	host:port
LOG_LEVEL	Nivel de detalle del log. Usa info o superior en producción.	Varía según el servicio	debug, info, warn, error
ENV_NAME	Etiqueta de entorno. En SLC, se normaliza a una lista de valores permitidos.	Varía según el servicio	SLC: production, staging, uat, development, local

Algunos servicios usan un SERVER_PORT numérico en lugar de SERVER_ADDRESS o junto con esta. En las releases que adoptan el puerto de health, HEALTH_PORT habilita un listener separado. Sin valor, no hay listener de health. Los charts y ejemplos configuran 8099. Mantén ese puerto interno. Las releases anteriores pueden usar el puerto principal o un puerto dedicado del worker. Consulta Puertos de red predeterminados y Salud y readiness.

En las releases que usan el ciclo de vida actual del servidor compartido, SHUTDOWN_DRAIN_DELAY acepta una duración Go no negativa. Un valor inválido o negativo impide el inicio. Cuando el servicio controla SIGTERM en un pod Kubernetes, el valor predeterminado es 15s; en los demás casos, es 0. Ante la señal, el servicio anuncia la detención y los listeners siguen atendiendo durante el drain. Después del drain, SHUTDOWN_TIMEOUT es un presupuesto compartido para HTTP, gRPC, admin y hooks de detención.

Antes de actualizar un despliegue BYOC a una release que mueve readiness al puerto de health:

1. Consulta la release del producto y combina su imagen y chart según el README del chart del producto.
2. Permite el tráfico TCP del nodo al pod en el puerto 8099 de la red interna, incluidos los firewalls del host o grupos de seguridad. Mantén privado el puerto de health.
3. Apunta los health checks del balanceador de carga a /health en el puerto principal. GKE Ingress y AGIC pueden recurrir a GET /, que devuelve 404.
4. Actualiza las sondas internas y el monitoreo para usar el puerto de health de la release que lo adopta. Mantén sin cambios el puerto principal de la API. Comprueba readiness, liveness y el presupuesto de detención antes de completar la actualización.

​

Almacenes de datos

Todo servicio que persiste estado se conecta a uno o más almacenes de datos. El prefijo de la variable depende del almacén y, en algunos servicios, de la base de datos lógica. La siguiente tabla muestra la forma común. Consulta la página de cada producto para conocer los nombres exactos.

Variable	Descripción	Predeterminado	Valores permitidos
POSTGRES_HOST / POSTGRES_PORT	Host y puerto de PostgreSQL.	Varía según el servicio	Host / puerto
POSTGRES_USER / POSTGRES_PASSWORD	Credenciales de conexión. La contraseña es un secreto. Inyéctala en el momento del despliegue y nunca la subas al repositorio.	Varía según el servicio	Cadena / secreto
POSTGRES_NAME / POSTGRES_DB / DB_NAME	Nombre de la base de datos. La clave exacta varía según el servicio: POSTGRES_NAME (por ejemplo, STA, SLC, SISBAJUD, Consignado), POSTGRES_DB (SPB, SPI, Boleto) o DB_NAME (Pix Indirect). Midaz la organiza por base de datos lógica como DB_{MODULE}_NAME. Consulta la página de cada producto.	Varía según el servicio	Cadena
POSTGRES_SSLMODE	Modo de TLS de libpq. Usa require o un nivel más estricto en producción.	Varía según el servicio	disable, require, verify-ca, verify-full
POSTGRES_REPLICA_*	Conexión opcional de réplica de lectura (misma forma que la principal).	—	Host / puerto / credenciales
MONGO_URI / MONGO_HOST / MONGO_PORT	Conexión a MongoDB, como URI completa o como host y puerto por separado.	—	Cadena de conexión / host / puerto
MONGO_TLS_CA_CERT	Certificado CA en PEM codificado en Base64 para TLS (por ejemplo, un servicio de MongoDB administrado).	—	Base64 PEM
REDIS_HOST / REDIS_PASSWORD	Endpoint de Redis/Valkey y contraseña de autenticación (secreto).	Varía según el servicio	host:port / secreto
REDIS_TLS / REDIS_CA_CERT	Habilita TLS hacia Redis y proporciona un certificado CA en PEM codificado en Base64. En SLC, REDIS_TLS=true requiere que REDIS_CA_CERT no esté vacío.	false / —	true, false / base64 PEM
RABBITMQ_HOST / RABBITMQ_URI	Host del broker y esquema de conexión. Usa amqps en producción.	Varía según el servicio	Host / amqp, amqps
RABBITMQ_DEFAULT_USER / RABBITMQ_DEFAULT_PASS	Credenciales del broker (la contraseña es un secreto). En SLC, cuando RabbitMQ está habilitado y su URL no tiene credenciales, declara explícitamente tanto RABBITMQ_DEFAULT_USER como RABBITMQ_DEFAULT_PASS.	—	Cadena / secreto

No todos los servicios usan todos los almacenes, y los prefijos varían. Midaz organiza las conexiones por base de datos lógica (por ejemplo, DB_ONBOARDING_*, DB_TRANSACTION_*, MONGO_CRM_*).

​

Configuración de runtime

Variable	Descripción	Predeterminado	Valores permitidos
SYSTEMPLANE_ENABLED	Habilita la API de administración de configuración en tiempo de ejecución de systemplane, en los servicios que exponen este interruptor. Consulta la página de cada servicio.	Varía según el servicio	true, false

Cuando está habilitada, el servicio expone un plano para leer y escribir la configuración en tiempo de ejecución. Consulta Systemplane para conocer la API y los espacios de nombres.

​

Streaming y outbox

Si la publicación de eventos está activa de forma predeterminada, y qué interruptor la controla, varía según el servicio. Consulta la página de cada producto para conocer su contrato, por ejemplo SPI y SILOC.

Variable	Descripción	Predeterminado	Valores permitidos
STREAMING_ENABLED	Habilita el productor de eventos, en los servicios que exponen este interruptor.	Varía según el servicio	true, false
STREAMING_BROKERS	Brokers de arranque de Kafka/RedPanda, como una lista de host:port separada por comas. Obligatoria al iniciar en los servicios cuyo streaming no tiene modo deshabilitado.	—	host:port CSV
STREAMING_CLOUDEVENTS_SOURCE	El source de CloudEvents que se graba en cada evento que emite el servicio. Varios productos aceptan exactamente un literal y se niegan a arrancar con cualquier otro, así que toma el valor de la página propia del producto.	Varía según el servicio	El literal que exige el producto
STREAMING_EVENT_POLICIES	Anulaciones de política de entrega por evento, como entradas event.key.attribute=value separadas por comas, punto y coma o saltos de línea (por ejemplo transaction.created.enabled=true,transaction.created.outbox=always). Los atributos son enabled, direct, outbox y dlq. Si se deja vacío, se conserva la política predeterminada de cada evento.	—	Lista event.key.attribute=value
STREAMING_COMPRESSION	Códec de compresión del productor, en los servicios que lo leen.	lz4	none, gzip, snappy, lz4, zstd
STREAMING_REQUIRED_ACKS	Nivel de confirmación (ack) del productor, en los servicios que lo leen.	all	all, leader, none
OUTBOX_ENABLED	Habilita el despachador del outbox transaccional (donde el servicio lo expone por separado).	Varía según el servicio	true, false

Las variables que protegen la conexión con el broker varían según el servicio. Algunos servicios leen STREAMING_SASL_* y STREAMING_TLS_*, y Consignado lee STREAMING_KAFKA_SASL_* y STREAMING_KAFKA_TLS_*. Configúralas cuando tu broker exija autenticación o TLS, y toma los nombres de la página propia del producto.

​

Descubrimiento de servicios

En los servicios que admiten el descubrimiento de servicios con Consul, está deshabilitado de forma predeterminada. Cuando está habilitado, el servicio se registra a sí mismo y resuelve a sus pares a través de Consul en lugar de usar direcciones estáticas.

Variable	Descripción	Predeterminado	Valores permitidos
SD_ENABLED	Habilita el descubrimiento de servicios con Consul.	false	true, false
SD_EXTERNAL_ADDRESS / SD_INTERNAL_ADDRESS	Direcciones anunciadas. Obligatorias cuando está habilitado.	—	host:port
SD_TLS / SD_TLS_SKIP_VERIFY	Habilita TLS hacia Consul y (por separado) omite la verificación del certificado.	false	true, false
SD_TOKEN	Token ACL de Consul (secreto).	—	Secreto

Algunos servicios usan alias heredados (SD_ADVERTISE_*, CONSUL_ADDR) para el mismo comportamiento.

​

Observabilidad

La telemetría funciona por envío (push, OTLP). Algunos servicios también exponen un endpoint /metrics para el scraping de Prometheus. Consulta Salud y readiness.

Variable	Descripción	Predeterminado	Valores permitidos
ENABLE_TELEMETRY	Habilita la instrumentación de OpenTelemetry.	false	true, false
OTEL_EXPORTER_OTLP_ENDPOINT	Endpoint del colector OTLP. Usa un endpoint https:// en producción.	Varía según el servicio	URL
ALLOW_INSECURE_OTEL	Permite que un servicio envíe telemetría a un endpoint OTLP en texto plano (http:// o sin esquema) en producción. Sin ella, muchos servicios no se inician con un endpoint en texto plano en producción. Usa un motivo corto. Para mantener TLS obligatorio, déjala sin valor.	Sin valor	String
OTEL_RESOURCE_SERVICE_NAME	Nombre del servicio adjunto a la telemetría exportada.	Predeterminado del servicio	Cadena
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT	Etiqueta de entorno adjunta a la telemetría exportada.	Varía según el servicio	Cadena

​

Autenticación de plugins

Los servicios de Lerian pueden autenticar rutas protegidas a través de Access Manager (respaldado por Caradhras). El interruptor de autenticación, el nombre de su variable y su valor predeterminado varían según el servicio. Habilita siempre la autenticación en producción. Consulta la página de variables de entorno propia de cada producto o riel para conocer el nombre autoritativo del interruptor, su valor predeterminado y las rutas que protege.

Variable	Descripción	Predeterminado	Valores permitidos
PLUGIN_AUTH_ENABLED / AUTH_ENABLED	Exige la autenticación de Access Manager en las rutas protegidas. El nombre y el valor predeterminado varían según el servicio.	Varía según el servicio	true, false
PLUGIN_AUTH_ADDRESS / PLUGIN_AUTH_HOST / AUTH_ADDRESS	Dirección del servicio de Access Manager. Obligatoria cuando está habilitado.	—	Dirección

​

Variables por producto

Cada producto agrega sus propias variables: prefijos de almacenamiento de datos, URLs de integración, ajustes de workers e interruptores de funcionalidad. La página de cada producto tiene la lista completa y actualizada, por ejemplo:

Midaz

Tracer

Reporter

Lender