Variables de entorno

Variables de entorno de despliegue de Lerian STA: entorno objetivo del BACEN, almacenamiento S3, claves maestras de cifrado de sobre y trust store.

Lerian STA es el rail propiedad de Lerian que transmite y recibe archivos con el hub STA de BACEN. Defines estas variables en el momento del despliegue. Un reinicio del servicio hace que surtan efecto. Cada servicio Go de Lerian comparte un backbone universal: servidor, almacenes de datos, multi-tenancy, telemetría, autenticación de plugins y licenciamiento. La referencia de configuración BYOC documenta ese backbone una sola vez. Esta página cubre solo las variables distintivas de Lerian STA.

En las tablas siguientes, la columna Valor por defecto / Requerida muestra el valor por defecto. Un calificador en negrita marca una variable que debes definir, como Requerida o Requerida en producción. — significa que no hay valor por defecto. Una variable marcada como Sensible contiene material de credenciales o claves. Inyéctala desde tu gestor de secretos en el momento del despliegue. Nunca guardes un valor en el repositorio.

​

Servicio y runtime

Variable	Valor por defecto / Requerida	Descripción
SERVER_ADDRESS	—	Dirección de escucha HTTP principal. Defínela explícitamente: la etiqueta envDefault :4028 no se materializa en runtime. Las sondas de liveness, readiness, métricas y versión se enlazan a este mismo puerto.
SYSTEMPLANE_ENABLED	false	Habilita la API de administración de configuración en tiempo de ejecución de Systemplane bajo el prefijo /system en el puerto principal. Desactivada por defecto (modo solo variables de entorno).
DEFAULT_TENANT_ID	—	UUID opcional usado solo como fallback de ce-tenantid de streaming/outbox cuando un evento no tiene ID de tenant; no se inyecta en el contexto ordinario de solicitudes o transferencias single-tenant.
BACEN_ENVIRONMENT	homologation	Selecciona el objetivo STA de BACEN upstream para la sonda de conectividad: homologation (staging) o production (en vivo). Un valor no reconocido recae en homologation, de modo que un stack no productivo no pueda enrutar tráfico al servicio de BACEN en vivo.

Lerian STA expone /health (liveness) y /readyz (readiness) en el puerto principal, además de /version y /metrics. Cuando habilitas la multi-tenancy, también expone GET /readyz/tenant/{id}. Consulta Salud y readiness para el contrato de las sondas.

​

Almacenamiento de objetos

Lerian STA persiste los bytes de transferencia y las descargas entrantes en un almacén de objetos compatible con S3. Cada subsistema configura su propia conexión a través del AWS SDK, de modo que el mismo cableado sirve para AWS S3, MinIO o un almacén local.

Variable	Valor por defecto / Requerida	Descripción
TRANSFER_OBJECT_STORAGE_BUCKET	Requerida en producción	Bucket que contiene ambas direcciones de transferencia, indexado por prefijo de dirección. El arranque de producción se rechaza si está vacío, independientemente de que las transferencias entrantes estén habilitadas.
TRANSFER_INBOUND_ENABLED	false	Habilita la pipeline de transferencia entrante (extraída por BACEN). No cambia el requisito del bucket en producción porque las transferencias salientes también lo usan.
TRANSFER_INBOUND_MAX_FILE_SIZE_BYTES	0	Un valor de 0 significa que no hay techo para el tamaño de archivo entrante anunciado por BACEN. Define un valor positivo para omitir archivos mayores antes de escribir byte alguno.
AWS_REGION	—	Región para AWS Secrets Manager M2M y, cuando MASTER_KEY_KMS_REGION está vacío, el fallback de AWS KMS. No configura el almacenamiento de objetos.
AWS_ACCESS_KEY_ID	—	Clave de acceso para el almacén de objetos. Sensible. Déjala sin definir cuando un rol IAM adjunto aporte las credenciales.
AWS_SECRET_ACCESS_KEY	—	Clave secreta para el almacén de objetos. Sensible. Déjala sin definir cuando un rol IAM adjunto aporte las credenciales.

​

Cifrado de sobre

Lerian STA protege las credenciales de operador con cifrado de sobre AES-GCM. El proceso del manager siempre necesita el material de clave maestra. Un valor faltante o malformado aborta el arranque.

Variable	Valor por defecto / Requerida	Descripción
MASTER_KEY_PROVIDER	envvar	Origen de la clave de cifrado de sobre: envvar (clave leída de MASTER_KEYS) o aws-kms (clave envuelta por un KMS en la nube).
MASTER_KEY_VERSION	Requerida	Selecciona la versión de clave maestra actualmente activa. Debe coincidir con una versión presente en MASTER_KEYS.
MASTER_KEYS	Requerida	Pares version:key separados por comas. Sensible. Con envvar, cada valor es una clave AES-256 de 64 caracteres hex: version:<64-hex-key>. Con aws-kms, cada valor es texto cifrado de KMS en base64: version:<base64-ciphertext>, que se descifra en el proceso. Obtenla de tu gestor de secretos: un valor faltante o malformado aborta el arranque.
MASTER_KEY_KMS_KEY_ID	Requerida si aws-kms	Identificador de la clave AWS KMS usada para descifrar el texto cifrado de MASTER_KEYS. Con aws-kms, el texto cifrado se descifra en el proceso de STA.
CREDENTIALS_RECOVERY_ON_BOOT	false	Establécela explícitamente en true para ejecutar una vez al arrancar el barrido de recuperación de credenciales del lado worker dejadas a mitad de rotación por un proceso anterior.

​

Trust store

Cada tenant sube los certificados raíz X.509 que Lerian STA usa para validar el certificado TLS del servidor de BACEN. STA se autentica ante BACEN con credenciales de operador HTTP Basic y no adjunta certificado de cliente. El módulo de trust store siempre está activado. Lerian STA persiste los cuerpos PEM de los certificados en el almacén de objetos, por lo que necesita la conexión al bucket del trust store.

Variable	Valor por defecto / Requerida	Descripción
TRUST_STORE_S3_BUCKET	Requerida	Bucket que contiene los PEM de certificados del trust store por tenant. El arranque falla sin él.
TRUST_STORE_S3_REGION	us-east-1	Región para el bucket del trust store.
TRUST_STORE_S3_ENDPOINT	—	Endpoint del almacén de objetos. Déjalo vacío para recaer en el endpoint por defecto de AWS S3.
TRUST_STORE_S3_PATH_STYLE	false	Usa el direccionamiento path-style. Requerido para MinIO o un almacén local; déjalo en false para AWS S3.
TRUST_STORE_MAX_CERT_SIZE_BYTES	65536	Tamaño máximo aceptado de un PEM de certificado subido.
TRUST_STORE_EXPIRING_SOON_DAYS	30	Ventana, en días, a partir de la cual se reporta un certificado como próximo a expirar. Ajustable por el operador con recarga en caliente.
TRUST_STORE_DEFAULT_PAGE_SIZE	25	Tamaño de página por defecto para la API de listado del trust store.
TRUST_STORE_MAX_PAGE_SIZE	100	Tamaño de página máximo para la API de listado del trust store.

Lerian STA ejecuta su pipeline de auditoría en un worker dedicado. El publicador, el consumidor y el generador de exportación soportan modos single-tenant y multitenant; el generador también necesita su bucket S3. El gestor de particiones, la limpieza y el verificador requieren multi-tenancy. Configura explícitamente las flags de habilitación y los parámetros requeridos mediante las familias AUDIT_PUBLISHER_*, AUDIT_CONSUMER_*, AUDIT_PARTITION_*, AUDIT_CLEANUP_*, AUDIT_VERIFIER_*, AUDIT_EXPORT_GENERATOR_* y AUDIT_EXPORT_RATE_LIMIT_*: las etiquetas envDefault no se materializan en general.