Saltar a contenido

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, Settings pasa a extra="ignore": las variables del .env que no son campos de Settings se 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 forbid y un .env por 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 en Settings variables 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=true deja DATABASE_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 .env compartido. Las que deben diferir por servicio no pueden ir en él: van en el entorno del proceso, que tiene prioridad sobre el .env.
  • El .env compartido puede contener secretos de otros servicios en el disco de este; no se cargan en Settings, 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.