Docker
Separación entre imagen, configuración de ambiente y secretos.
Una imagen debe representar el mismo artefacto entre desarrollo, staging y producción. Lo que cambia por ambiente se inyecta en runtime mediante variables, archivos montados, secrets o servicios de configuración.
misma image por digest
+ configuración de desarrollo
→ entorno de desarrollo
misma image por digest
+ configuración de producción
→ entorno de producciónReconstruir una imagen por ambiente rompe trazabilidad: deja de ser posible demostrar que producción ejecuta exactamente el artefacto validado en staging.
El canal debe elegirse según sensibilidad, tamaño, rotación y forma de consumo.
Existe durante build según alcance:
ARG NODE_VERSION=22
FROM node:${NODE_VERSION}-slimNo queda disponible automáticamente como variable de runtime, pero puede aparecer en logs, historial o outputs. No es un secret store.
Persiste en metadata y runtime:
ENV NODE_ENV=production \
PORT=3000Es apropiado para defaults no sensibles ligados a la imagen. Puede sobrescribirse al crear el contenedor.
| Aspecto | ARG | ENV |
|---|---|---|
| Build | Sí | Sí desde su declaración |
| Runtime predeterminado | No | Sí |
| Secretos | No | No recomendado |
| Afecta resultado/cache | Puede | Puede |
docker run \
--env NODE_ENV=production \
--env PORT=3000 \
my-apiTambién puede heredarse un valor del shell:
export LOG_LEVEL=info
docker run --env LOG_LEVEL my-apiEste patrón puede producir valores ausentes o diferentes entre terminales. Para despliegues, prefiere configuración explícita y validada.
docker run --env-file /etc/my-api/runtime.env my-apiEjemplo:
NODE_ENV=production
PORT=3000
LOG_LEVEL=info
REQUEST_TIMEOUT_MS=10000Un env file:
Mantén un .env.example con nombres y valores seguros de muestra, no secretos.
La configuración puede venir de:
ENV de la image;Una variable definida en varios niveles crea ambigüedad. Documenta una política única y utiliza:
docker inspect container --format '{{json .Config.Env}}'para revisar el resultado efectivo. Evita imprimir valores sensibles en soporte o tickets.
La aplicación debe validar configuración antes de aceptar tráfico.
Ejemplo TypeScript con Zod:
import { z } from 'zod';
const environmentSchema = z.object({
NODE_ENV: z.enum(['development', 'test', 'production']),
PORT: z.coerce.number().int().min(1).max(65535),
DATABASE_URL: z.string().url(),
REQUEST_TIMEOUT_MS: z.coerce.number().int().positive().default(10_000),
});
export const environment = environmentSchema.parse(process.env);Beneficios:
Los mensajes de error no deben mostrar passwords o URLs completas con credenciales.
Todas las variables de entorno llegan como strings.
Errores frecuentes:
if (process.env.FEATURE_ENABLED) {
// "false" también es truthy
}Convierte explícitamente y define formatos aceptados.
Unidades también deben formar parte del nombre o esquema:
REQUEST_TIMEOUT_MS=10000
CACHE_TTL_SECONDS=300Evita TIMEOUT=10 sin unidad.
Estos estados no son equivalentes:
VARIABLE no definida
VARIABLE=
VARIABLE=""La aplicación debe decidir si vacío significa borrar, usar default o error. Herramientas de Compose y shells pueden interpolar valores de manera diferente.
Environment es conveniente, pero puede aparecer en:
docker inspect;Para secretos de alto impacto, prefiere mounts de archivos o integración con un secret manager.
Ejemplo de consumo por archivo:
/run/secrets/db_passwordLa aplicación puede soportar convención _FILE:
DB_PASSWORD_FILE=/run/secrets/db_passwordEl archivo también necesita permisos y rotación. No existe un canal sin responsabilidades.
Un archivo montado es útil para contenido estructurado:
docker run \
--mount type=bind,src=/etc/my-api/config.yaml,dst=/app/config.yaml,readonly \
my-apiVentajas:
Riesgos:
La configuración debe administrarse y distribuirse, no editarse dentro del container.
Los flags de runtime permiten activar comportamiento sin construir otra image. Pero deben tener:
Un flag no debe esconder durante años dos arquitecturas completas dentro del código.
Algunas aplicaciones consultan un servicio central. Esto permite cambios sin recrear, pero introduce:
Define qué valores pueden cambiar en caliente y cuáles requieren restart. No todas las librerías releen process.env; normalmente el environment se fija al crear el proceso.
Rotar una credencial puede requerir:
Cambiar un archivo en host no garantiza que la aplicación lo relea. Pools existentes pueden conservar conexiones autenticadas con la credencial anterior.
No registres todo process.env al iniciar. Puede incluir:
Registra únicamente nombres permitidos y valores no sensibles:
console.info({
nodeEnv: environment.NODE_ENV,
port: environment.PORT,
requestTimeoutMs: environment.REQUEST_TIMEOUT_MS,
});Variables usadas durante un build de frontend pueden quedar incorporadas al bundle público. Un valor llamado API_SECRET no se vuelve privado por estar en .env.
Distingue:
En Next.js y otros frameworks, los prefijos públicos suelen indicar que el valor llegará al navegador. Trátalo como público.
Image:
registry.example.com/api@sha256:ADesarrollo:
LOG_LEVEL=debug
DATABASE_URL=postgres://db-dev/app
FEATURE_NEW_CHECKOUT=trueStaging:
LOG_LEVEL=info
DATABASE_URL=postgres://db-staging/app
FEATURE_NEW_CHECKOUT=trueProducción:
LOG_LEVEL=warn
DATABASE_URL_FILE=/run/secrets/database_url
FEATURE_NEW_CHECKOUT=falseEl digest es el mismo. Cambian dependencias y configuración externas.
La precedencia puede producir un valor inesperado. Inspecciona configuración resuelta.
El parser del env file y quoting importan. Prueba el formato real; no copies sintaxis de shell sin verificar.
Un secreto o archivo puede incluir \r y causar autenticación inválida.
Leer un archivo mediante cat o editor puede conservar newline. La aplicación debe conocer el formato, no aplicar trim() indiscriminadamente a certificados o datos binarios.
Las variables se fijaron al crear la instancia. Debes recrear o usar un canal dinámico.
Si falta AUTH_ENABLED, la app desactiva auth. Los defaults de seguridad deben fallar cerrados.
Consecuencia: secreto en layers y artefacto distinto por ambiente.
Corrección: runtime config y secret mounts.
Consecuencia: "false" se interpreta como true o un timeout inválido aparece tarde.
Corrección: schema al inicio.
Consecuencia: staging y producción ejecutan artefactos distintos.
Corrección: build once, configure at runtime.
Consecuencia: filtración de credenciales.
Corrección: allowlist de valores no sensibles.
Consecuencia: precedencia impredecible.
Corrección: una fuente por categoría y documentación clara.
ARG, ENV y layers..env.example sin credenciales.ARG y ENV cumplen funciones distintas, pero ninguno es un vault.process.env?Puertos, EXPOSE y publicación, donde se diferencia el puerto del proceso, la red del container y la exposición en el host.