Aurora Libros funciona en tu máquina, y funciona bien. Producción es otra cosa: allí nadie reinicia el contenedor a mano cuando se cuelga, la configuración cambia entre entornos y una petición cortada a mitad es un pedido perdido. Esta lección convierte tu imagen 1.3.0 en la 2.0.0: la que un orquestador puede arrancar, matar y volver a arrancar cien veces al día sin que un cliente se entere.

1. Qué distingue una imagen de producción
2. Los doce factores aplicados a la configuración
3. Validar la configuración al arrancar y fallar rápido
4. PID 1 y el problema de los zombis
5. Un proceso por contenedor
6. El apagado ordenado completo
7. El periodo de gracia y la petición más larga
8. Las tres sondas: liveness, readiness y startup
9. /salud/vivo y /salud/listo en aurora-api
10. Reproducibilidad: digests, lockfile y etiquetas OCI
11. Elegir límites de recursos con datos reales
12. El límite de memoria y el heap de Node
13. El Dockerfile definitivo de Aurora Libros
14. El compose.prod.yaml de la versión 2.0.0
15. Checklist de quince puntos

Advertencia. Los valores de límites, plazos y sondas de esta lección son puntos de partida razonados con datos de Aurora Libros, no una política. Los umbrales de recursos, las ventanas de apagado y el tratamiento de secretos en producción deben validarse con el responsable de infraestructura, seguridad o compliance de tu organización.

No es una diferencia de tecnología: es una diferencia de supuestos. En desarrollo supones que hay alguien mirando; en producción supones que no.

Las cuatro últimas filas separan una imagen que funciona de una que se puede operar; las tres primeras ya las resolviste en el módulo 5.

La regla del tercer factor de la metodología twelve-factor es tajante: la configuración vive en el entorno, nunca en la imagen. La prueba práctica es la pregunta del código abierto: ¿podrías publicar esta imagen ahora mismo en un registro público sin filtrar nada? Si la respuesta es no, tienes configuración dentro.

De ahí se deriva la propiedad más valiosa de todo el módulo: una imagen, muchos entornos. El mismo digest que pasó las pruebas en CI es el que corre en staging y el que corre en producción; lo único que cambia son las variables que le inyectas. Si reconstruyeras la imagen para producción, estarías desplegando un artefacto que nadie ha probado. Lo que sigue es cómo se reparte cada cosa.

El peor fallo de configuración es el silencioso: el contenedor arranca, se declara sano, recibe tráfico y entonces descubre que DB_PASSWORD estaba vacía. Para cuando lo sabes, el balanceador ya le ha mandado clientes.

La solución es fail fast: validar todo al arrancar y salir con código distinto de cero si algo falta.

Tres decisiones importantes. La primera: nada del resto del código lee process.env; todos importan config.js, así que existe un único sitio donde saber qué configura la aplicación. La segunda: el _FILE gana sobre la variable directa, de modo que el mismo código sirve para desarrollo (variable) y para producción (secreto montado). La tercera: el código de salida 78 no es decorativo; distinguirlo del 1 genérico permite que el orquestador —y tú, leyendo docker inspect— sepan que no es un fallo transitorio y que reiniciar mil veces no lo va a arreglar. Lo comprobarás en el ejercicio 1: el fallo llega en el segundo 0, con el nombre exacto de la variable que falta, en vez de un 502 a las tres de la madrugada.

En 03-02 viste que el proceso principal del contenedor es el PID 1. Producción añade un matiz que en desarrollo no molesta: en Linux, el PID 1 tiene dos responsabilidades especiales del proceso init.

1. Adoptar huérfanos. Cuando un proceso muere dejando hijos, esos hijos pasan a colgar del PID 1.
2. Recoger zombis. Un proceso terminado permanece en estado Z hasta que su padre llama a wait() para leer su código de salida. Si nadie lo hace, la entrada nunca se libera.

Node.js no hace lo segundo: no es un init. Si tu API lanza subprocesos —una conversión de imagen, un pg_dump—, cada uno deja un zombi que ocupa una entrada de la tabla de procesos, y los cuentas con docker compose exec aurora-api ps -eo stat | grep -c Z. Con pids_limit: 200, doscientos zombis y el contenedor no puede crear un proceso más. La solución es un init mínimo delante:

Un detalle que cuesta caro: el PID 1 tiene desactivadas las acciones por defecto de las señales. Si tu proceso no instala un manejador de SIGTERM, la señal se ignora, docker stop espera diez segundos y te lo mata con SIGKILL. Ese es el origen real de la mayoría de los "mi contenedor tarda diez segundos en parar".

La tentación de meter supervisord, systemd o un cron dentro del contenedor aparece en cuanto necesitas una segunda cosa. Resístete, por razones concretas:

• El estado se vuelve opaco. Docker solo ve el gestor. Si Node muere y supervisord sigue vivo, el contenedor está "sano" con la aplicación caída.
• Los reinicios dejan de funcionar. restart: always y el orquestador reaccionan a la muerte del PID 1, que ya no ocurre nunca.
• Los logs se mezclan y pierden su origen; docker logs deja de ser útil.
• El escalado se acopla. Si la API necesita tres réplicas y el cron una, no puedes.
• La imagen engorda y su superficie de ataque crece.

Las tareas periódicas de Aurora Libros —la copia de la base de datos de 05-02— son un servicio aparte con su propio ciclo de vida, no un cron escondido. La única excepción legítima es el patrón sidecar: dos contenedores distintos que comparten red o volumen, cada uno con su PID 1.

Cuando el orquestador retira una réplica manda SIGTERM y arranca un cronómetro. Lo que hagas en esos segundos decide si los clientes que estaban comprando terminan su compra o ven un error.

El paso 2 es el que casi todo el mundo se salta y el que más errores evita. Entre que tu Pod deja de estar listo y que el balanceador deja de mandarle tráfico pasan unos segundos: la actualización de las tablas de enrutado no es instantánea. Si cierras el listener inmediatamente, las peticiones que ya iban de camino se estrellan contra un puerto cerrado. Esperar unos segundos con el listener abierto pero la readiness en rojo elimina esa ventana.

El orden del paso 4 también importa: primero Redis y después PostgreSQL, al revés de como se abrieron, porque una petición en curso puede necesitar la base de datos después de fallar en la caché.

La regla es aritmética:

Para Aurora Libros, con la petición más lenta medida en 4 s (el listado completo sin caché), 5 s de espera de readiness y ~1 s de cierre de conexiones: 5 + 4 + 1 = 10 s, y se configuran 15 s para tener margen.

Fíjate en que el plazo de la plataforma es siempre mayor que el de la aplicación: quien debe decidir terminar es tu código, no el SIGKILL. Si Docker mata el proceso antes de que acabe, el apagado ordenado no ha servido de nada.

El HEALTHCHECK de 02-04 respondía a una sola pregunta. En producción hay tres, y confundirlas provoca caídas espectaculares.

El error clásico es usar el mismo endpoint para las tres, y su consecuencia es una caída total en cascada. Imagina que /salud comprueba PostgreSQL, como el tuyo del módulo 5, y que la base de datos se cae treinta segundos por un failover:

1. La readiness falla en las tres réplicas: correcto, no tiene sentido mandarles tráfico.
2. La liveness también falla, porque es el mismo endpoint.
3. El orquestador reinicia las tres réplicas de la API.
4. La base de datos vuelve, pero las réplicas están arrancando desde cero.
5. Las tres se reconectan a la vez, saturan el pool y la liveness vuelve a fallar.

Has convertido una incidencia de 30 segundos en un bucle de reinicios. La regla que lo evita es simple: la liveness no comprueba dependencias. Reiniciar tu proceso no arregla una base de datos caída; lo único que hace es empeorarlo.

La sonda de startup resuelve un problema distinto: si arrancar tarda 40 s (migraciones, calentamiento de caché) y la liveness tiene un umbral de 10 s, el contenedor se reinicia eternamente sin llegar nunca a arrancar. La startup suspende a las otras dos hasta que pasa por primera vez.

La decisión de negocio está en la penúltima línea: Redis caído no quita a la réplica del balanceo, porque el cache-aside de Aurora Libros degrada a origen: db y sigue vendiendo libros, más lento. PostgreSQL caído sí, porque sin catálogo no hay nada que servir. Esa distinción entre dependencia dura y blanda es tuya, no de Docker, y conviene escribirla en el código junto a la sonda.

Que la imagen de hoy y la de dentro de seis meses sean la misma no es purismo: es la única forma de que un rollback sirva de algo.

Poner memory: 2G "por si acaso" tiene dos costes: el orquestador reserva memoria que nadie usa y cabe menos en cada nodo. Poner poco tiene otro: OOM kill con código 137 en hora punta. Se mide con quince minutos de muestreo bajo carga representativa, volcando docker stats --no-stream --format '{{.Name}};{{.MemUsage}};{{.CPUPerc}}' en bucle a un CSV.

Las reglas que aplican esos números:

• Memoria: pico observado × 2 aproximadamente, redondeando a una potencia cómoda. La memoria no es comprimible: pasarse del límite significa muerte, no lentitud.
• CPU: no ahogues los picos. La CPU sí es comprimible; un límite bajo solo produce latencia. aurora-db recibe 2 CPU porque un VACUUM o un pg_dump deben poder correr.
• aurora-cache con --maxmemory 200mb necesita un límite de contenedor por encima de esos 200 MB: Redis usa memoria además de la de los datos. 256M es el mínimo defendible.
• Deja siempre las requests por debajo de los limits en Kubernetes (06-05): las requests reservan y deciden dónde cabe el Pod; los limits cortan.

Aquí hay una trampa concreta. El heap de V8 tiene su propio máximo, independiente del cgroup. Si Node cree que puede usar 4 GB y el contenedor corta en 512 MB, el proceso muere por OOM sin lanzar ninguna excepción: el kernel lo mata antes de que el recolector de basura decida que hay presión. Compruébalo con docker run --rm --memory 512m node:22-alpine node -p 'v8.getHeapStatistics().heap_size_limit/1048576'.

Node 22 lee el cgroup y ajusta el límite razonablemente, pero conviene ser explícito, sobre todo porque el heap no es toda la memoria del proceso: los buffers, el código nativo y la pila viven fuera de él. La regla práctica es dejar al heap el 75 % del límite del contenedor, que es de dónde sale el ENV NODE_OPTIONS="--max-old-space-size=384" del Dockerfile. Con esa configuración, cuando la aplicación se acerque al techo, V8 recolectará agresivamente y, si de verdad no cabe, lanzará un heap out of memory que puedes registrar en vez de un 137 mudo.

El healthcheck de Compose usa /salud/listo y el HEALTHCHECK de la imagen usa /salud/vivo, a propósito: aquí la salud gobierna depends_on, es decir, "¿puedo mandarte tráfico?", que es exactamente la readiness.

• Reconstruir la imagen para cada entorno. Si staging y producción tienen imágenes distintas, no has probado lo que despliegas. Un artefacto, un digest, muchos entornos.
• La liveness comprueba la base de datos. Es el error más caro de esta lección: convierte una caída de la BD en un bucle de reinicios de toda la flota. La liveness solo responde "el proceso responde".
• Cerrar el listener nada más recibir SIGTERM. Sin la espera previa con la readiness en rojo, las peticiones ya enrutadas se pierden. Cinco segundos de margen eliminan casi todos los 502 de un despliegue.
• CMD npm start. npm se convierte en PID 1, no reenvía SIGTERM a Node y añade una capa inútil. Usa siempre CMD ["node", "src/server.js"].
• Confiar en los valores por defecto de la configuración. Un DB_HOST con defecto localhost no falla: se conecta al sitio equivocado. Lo obligatorio no tiene defecto.
• stop_grace_period menor que el plazo interno. Docker manda SIGKILL a mitad del drenaje y todo el trabajo de apagado ordenado se tira a la basura. Y latest en producción impide saber qué corre y hace imposible el rollback: etiqueta SemVer y, mejor, despliega por digest.
• Consejo: prueba el apagado. docker stop con hey mandando carga y cuenta cuántas peticiones fallan. Si no es cero, tu apagado ordenado no lo es.
• Consejo: registra la configuración efectiva al arrancar, con los secretos ocultos. Un log de arranque con db_host, pool_max y version ahorra horas de diagnóstico.

Ejercicio 1. Demuestra el fallo rápido: arranca aurora-api:2.0.0 sin DB_PASSWORD, comprueba que sale con código 78 en menos de un segundo con un mensaje que nombra la variable, y verifica que con DB_PASSWORD_FILE apuntando a un secreto sí arranca.

Ejercicio 2. Comprueba que el apagado ordenado funciona: genera carga contra /libros, ejecuta docker stop en mitad de la carga y mide cuántas peticiones fallaron. Después desactiva el manejador de SIGTERM y repite, comparando el tiempo de parada y los errores.

Ejercicio 3. Demuestra por qué la liveness no debe tocar la base de datos: para aurora-db y comprueba qué responden /salud/vivo y /salud/listo. Explica qué haría un orquestador con cada respuesta.

Solución 1.

Tres cosas quedan demostradas. El fallo tarda 0,4 segundos: el contenedor nunca llega a existir como servicio, así que ningún balanceador puede mandarle tráfico. El mensaje nombra la variable exacta, con lo que el diagnóstico es inmediato incluso para quien no conoce el código. Y el código 78 es distinguible: en un orquestador con reinicio automático, ver exit 78 repetido dice "no insistas, arregla la configuración", mientras que un exit 1 podría ser cualquier cosa.

En el segundo comando el secreto entra como fichero de solo lectura: nunca aparece en docker inspect ni en el historial del shell, y el código lo lee una sola vez al arrancar.

Solución 2.

Ahora el escenario contrario, sobrescribiendo el arranque para que el manejador no exista:

Los dos números cuentan la misma historia. 10,2 segundos es la firma inconfundible del problema: el proceso ignoró SIGTERM —recuerda, el PID 1 no tiene acción por defecto—, Docker esperó los 10 segundos completos de --time y lo mató con SIGKILL. Un SIGKILL no se puede capturar: las 152 conexiones abiertas se cortaron a mitad, y cada una es un cliente viendo un error.

Con el manejador, la parada tarda menos (6 s: los 5 de margen de readiness más el drenaje real) y ninguna petición falla. La lección operativa es que un despliegue de veinte réplicas sin apagado ordenado son miles de errores por versión publicada, y ninguno aparecerá en tus logs de aplicación, porque el proceso ya estaba muerto cuando ocurrieron.

Solución 3.

Ese par de respuestas es exactamente el comportamiento deseado. El proceso de Node está perfectamente sano —su bucle de eventos responde en milisegundos—, así que reiniciarlo no arreglaría nada; lo que ocurre es que no puede servir, y por eso deja de recibir tráfico y nada más.

Si /salud fuera a la vez liveness y readiness, como en la versión 1.3.0, ese mismo 503 habría producido: reinicio de las tres réplicas → 40 s sin servicio por el arranque → reconexión simultánea de tres pools contra una base de datos que acaba de volver → posible nuevo fallo → segundo reinicio. Una incidencia de 30 segundos de la base de datos convertida en varios minutos de caída total, causada íntegramente por la sonda mal diseñada.

Y fíjate en la tercera línea de la respuesta: cache: ok con db: error devuelve 503, pero el caso inverso —db: ok con cache: error— devuelve 200, porque el cache-aside degrada a origen: db. Esa asimetría es una decisión de producto codificada en la sonda: Aurora Libros prefiere vender libros despacio a no venderlos.

Has convertido una imagen que funciona en una imagen que se puede operar. La configuración salió por completo de la imagen y entró por el entorno, con un único config.js que la valida al arrancar y falla en 0,4 segundos con código 78 si falta algo obligatorio, en vez de reventar en la primera petición real; el patrón _FILE deja el mismo código sirviendo para tu portátil y para un clúster con secretos montados. Has resuelto el PID 1 con init: true para que los zombis no agoten tu pids_limit, y has entendido por qué meter un supervisord dentro rompe los reinicios, los logs y el escalado a la vez.

El apagado ordenado ya es completo y, sobre todo, está medido: cero peticiones perdidas frente a 152, con la espera de cinco segundos con la readiness en rojo antes de cerrar el listener —el paso que casi nadie implementa— y el cierre del cliente de Redis y del pool de PostgreSQL en orden inverso al de apertura. Sabes calcular el periodo de gracia a partir de la petición más larga y por qué stop_grace_period debe ser mayor que el plazo interno. Has separado las tres sondas con sus tres semánticas y has visto en vivo la razón: con PostgreSQL parado, /salud/vivo responde 200 y /salud/listo responde 503, así que la réplica pierde el tráfico pero no se reinicia; el endpoint único habría convertido treinta segundos de incidencia en varios minutos de caída total. Y has fijado la base por digest, npm ci con lockfile, etiquetas OCI con el commit, límites elegidos con quince minutos de docker stats en vez de a ojo, y un heap de V8 al 75 % del límite del cgroup para que un desbordamiento sea una excepción registrable y no un 137 mudo. Todo ello cristalizado en el Dockerfile y el compose.prod.yaml de aurora-api:2.0.0 y en una checklist de quince controles verificables uno a uno.

Ahora tienes el artefacto correcto, pero lo sigues construyendo tú, a mano, en tu portátil. En la siguiente lección, CI/CD con Docker, ese trabajo pasa a hacerlo una máquina: montarás el pipeline que, en cada git push, ejecuta el lint y las pruebas dentro de contenedores, construye la imagen multiarquitectura reutilizando la caché remota de BuildKit, la escanea con Trivy rompiendo la build ante vulnerabilidades críticas, la firma con Cosign, genera su SBOM y la publica en ghcr.io etiquetada automáticamente desde tu etiqueta de Git.