0013. Variables de entorno desconocidas: se ignoran en vez de impedir el arranque¶
Estado: Aceptado Fecha: 2026-10-06 Autor: David Garcia Módulo(s) afectado(s): app/core/config.py, .env.example, tests/unit/core/config/test_entorno.py Modifica a: ADR 0003
Contexto¶
El ADR 0003 configuró Settings con extra="forbid": cualquier variable de
.env que no fuera un campo de Settings impedía arrancar, para detectar
nombres mal escritos.
Existe un .env compartido entre los servicios de la plataforma.
Ese archivo trae variables que este servicio no usa pero otro sí (y al revés),
así que con forbid ningún servicio podría arrancar con él.
Decisión¶
- A propuesta de arquitectura,
Settingspasa aextra="ignore": las variables del.envque no son campos deSettingsse descartan sin error y no llegan a la configuración. - El resto del ADR 0003 se mantiene: las obligatorias (
APP_NAME,ENVIRONMENT,DATABASE_URL,DATABASE_SCHEMAS,JWT_JWKS_URL) siguen impidiendo arrancar si faltan, y las validaciones por entorno no cambian.
Alternativas descartadas¶
- Mantener
forbidy un.envpor servicio — obliga tener varios .env por servicio. - Prefijo por servicio (
env_prefix) — renombra todas las variables y rompe la convención compartida con los demás servicios. extra="allow"— guardaría enSettingsvariables de otros servicios (posibles secretos) sin validarlas.
Consecuencias¶
- Una variable opcional mal escrita ya no falla: se ignora y rige su valor
por defecto (
DATABSE_ECHO=truedejaDATABASE_ECHO=false). Los defaults de las opcionales son los seguros, así que el error degrada a «no se aplicó», no a una fuga. Una obligatoria mal escrita sigue fallando por ausente. - Las variables con el mismo nombre en varios servicios (
APP_NAME,DATABASE_SCHEMAS,DATABASE_URL,LOG_LEVEL...) toman el mismo valor en todos los que lean el.envcompartido. Las que deben diferir por servicio no pueden ir en él: van en el entorno del proceso, que tiene prioridad sobre el.env. - El
.envcompartido puede contener secretos de otros servicios en el disco de este; no se cargan enSettings, pero el archivo debe tratarse con los permisos del más sensible. - Las variables del contenedor de PostgreSQL ya no rompen el arranque si se
ponen en
.env, aunque siguen documentándose en.env.docker.example.
Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.