Al final de la lección anterior quedaron tres preguntas abiertas. ¿Cómo hacer que la migración de esquema se ejecute automáticamente antes de que arranque api-reservas, en lugar de como un Job aparte? ¿Cómo evitar que api-reservas entre en CrashLoopBackOff cuando arranca antes que postgres-reservas? ¿Cómo exportar métricas de PostgreSQL sin tocar la imagen oficial?

Las tres se responden igual: poniendo más de un contenedor en el mismo pod.

Desde la lección 02-01 sabemos que un pod es un grupo de contenedores que comparten espacio de nombres de red —y por tanto localhost—, volúmenes y ciclo de vida. Hasta ahora no habíamos aprovechado esa capacidad: todos los pods de Rutas Norte tienen un solo contenedor. En esta lección la usaremos con criterio, que es la parte difícil: la mayoría de pods multi-contenedor mal diseñados nacen de meter dos aplicaciones juntas porque "van relacionadas", y eso siempre acaba mal.

1. Cuándo un pod necesita varios contenedores y cuándo eso es un error
2. Init containers: preparación secuencial antes del arranque
3. Casos de uso de init containers en Rutas Norte
4. Diagnóstico de init containers fallidos
5. Sidecars nativos: init containers con restartPolicy: Always
6. Los tres patrones clásicos: sidecar, embajador y adaptador
7. Patrón sidecar: exportador de métricas junto a postgres-reservas
8. Patrón embajador: la conexión con la pasarela de pagos
9. Patrón adaptador: normalizar el log de worker-notificaciones
10. Orden de arranque y terminación, y el coste real

La regla de oro, formulada con precisión:

Dos procesos van en el mismo pod cuando están tan acoplados que no tiene sentido escalarlos, actualizarlos ni ejecutarlos por separado, y uno de ellos existe únicamente para servir al otro.

La consecuencia inmediata de compartir pod es que comparten destino: se programan en el mismo nodo, escalan juntos, se reinician juntos y se actualizan juntos. Si api-reservas necesita 5 réplicas y worker-notificaciones necesita 2, ponerlos en el mismo pod obliga a tener 5 de cada uno. Eso es un error de diseño, no una optimización.

Tres preguntas de control antes de añadir un contenedor a un pod existente:

1. ¿Necesitan escalar juntos siempre? Si la respuesta es no, son dos cargas de trabajo distintas.
2. ¿El segundo sirve exclusivamente al primero? Si otros pods también lo necesitan, es un Service aparte.
3. ¿Necesitan compartir localhost o un sistema de ficheros? Si no, no hay motivo técnico para juntarlos.

Kubernetes ofrece dos categorías de contenedor auxiliar:

• initContainers: se ejecutan antes, en orden, uno tras otro, y deben terminar con éxito.
• Contenedores auxiliares que acompañan al principal durante toda la vida del pod: los sidecars.

Un init container es un contenedor que se ejecuta hasta completarse antes de que arranque ningún contenedor principal. Si hay varios, se ejecutan en el orden en que aparecen en el manifiesto, cada uno esperando a que el anterior termine con éxito.

Propiedades que los distinguen de los contenedores normales:

Esa última fila es más útil de lo que parece: el init container puede usar una imagen con psql, curl o git que la imagen de producción no tiene, sin engordar la imagen final ni ampliar su superficie de ataque.

Sintaxis básica:

Los init containers también consumen recursos y participan en el cálculo de lo que el pod pide al scheduler. La fórmula efectiva es:

Es decir, un init container que pide 2 GiB obliga al scheduler a encontrar un nodo con 2 GiB libres, aunque la aplicación solo necesite 256 MiB. Conviene mantenerlos ligeros.

Cuando se levanta un entorno desde cero, api-reservas puede arrancar antes de que la base de datos esté lista, fallar al conectar, salir y entrar en CrashLoopBackOff. Acaba recuperándose, pero el arranque tarda minutos y los eventos se llenan de ruido que enmascara problemas reales.

pg_isready es una utilidad de la propia imagen de PostgreSQL que devuelve 0 si el servidor acepta conexiones. El bucle no tiene límite de intentos a propósito: el pod se quedará en Init:0/1 indefinidamente, lo que en kubectl get pods es una señal clarísima de "la base de datos no está disponible", mucho mejor que un CrashLoopBackOff cuya causa hay que ir a buscar en los logs.

Una nota de diseño honesta: esto no sustituye a que la aplicación gestione la reconexión. Si postgres-reservas se cae dos horas después, el init container ya no está para ayudar. Es una comodidad para el arranque, no una garantía de resiliencia.

Aquí retomamos la pregunta que dejó abierta la lección 06-03. La migración puede ir en un init container en lugar de en un Job separado:

Ventaja evidente: la migración va acoplada al despliegue. Es imposible desplegar el código 2.5.0 sin haber migrado, porque el contenedor de la aplicación no arranca si el init container no termina bien.

Pero hay una trampa importante que hay que conocer:

Con 4 réplicas de api-reservas, el init container de migración se ejecuta 4 veces, potencialmente en paralelo durante una actualización.

Consecuencias y mitigaciones:

• La migración debe ser idempotente y estar protegida por un lock. IF NOT EXISTS no basta: dos ALTER TABLE simultáneos pueden bloquearse mutuamente. Una herramienta de migraciones seria (Flyway, Liquibase, golang-migrate) toma un lock de aplicación en la base de datos y las demás instancias esperan.
• Si la migración tarda minutos, cada réplica paga esa espera, y el despliegue se alarga.

Recomendación para Rutas Norte: Job separado para migraciones grandes o destructivas (índices sobre millones de filas, cambios de tipo), initContainer para migraciones pequeñas e idempotentes del día a día.

tienda-web sirve HTML estático desde nginx, y la plantilla del pie de página cambia según el entorno. En vez de construir tres imágenes, un init container genera el fichero en un volumen compartido:

El mecanismo es exactamente el emptyDir de 05-01: un volumen vacío creado con el pod, compartido por todos sus contenedores. El init container escribe, nginx lee en solo lectura. Cuando el pod muere, el emptyDir desaparece, y no importa: se regenera en el arranque siguiente.

Los init containers tienen sus propios estados en la columna STATUS, y saber leerlos ahorra mucho tiempo.

Un caso real: api-reservas atascada porque la base de datos no responde.

Init:0/2 sostenido cuatro minutos: el primer init container (esperar-postgres) sigue en su bucle.

La clave está en -c <nombre>. Sin ese flag, kubectl logs intenta leer el contenedor principal, que aún no existe, y responde con un error confuso.

Otro caso: la migración falla.

Diagnóstico: la migración no es idempotente. Faltaba el IF NOT EXISTS.

Comandos útiles para inspeccionar init containers:

En la salida de describe, los init containers aparecen en un bloque Init Containers: antes del bloque Containers:, cada uno con su estado, su código de salida y su razón de terminación.

Durante años, un sidecar era simplemente "otro contenedor más en la lista containers". Funcionaba, pero tenía dos defectos graves que Kubernetes 1.29 resolvió y que están estables desde 1.33.

Problema 1: no hay orden de arranque. Todos los contenedores de containers arrancan en paralelo. Si el sidecar es un proxy por el que la aplicación tiene que salir a la red, y la aplicación arranca antes que el proxy, las primeras peticiones fallan.

Problema 2: los Jobs no terminaban nunca. Un Job cuyo pod tiene un sidecar era un problema sin solución limpia. El contenedor principal termina con éxito, pero el sidecar sigue vivo, así que el pod nunca alcanza Succeeded y el Job se queda colgado indefinidamente. La única salida eran apaños feos: ficheros centinela en un emptyDir, o que el contenedor principal matara al sidecar por la API.

Ese único campo cambia por completo la semántica del contenedor:

Las cuatro consecuencias prácticas, en orden de importancia:

1. Arranca antes que los contenedores principales, garantizando que el proxy o el exportador estén listos cuando la aplicación empieza a trabajar.
2. Sigue vivo durante toda la vida del pod y se reinicia si muere, cosa que un init container normal no hace.
3. Se termina después de los contenedores principales, así que un sidecar de logs captura los últimos mensajes del cierre.
4. No impide que un Job termine. Cuando los contenedores de containers acaban, el kubelet para los sidecars y el pod alcanza Succeeded. Esto desbloquea todo el trabajo por lotes con sidecars: un CronJob con proxy, con exportador de métricas o con adaptador de logs simplemente funciona.

Una precisión sobre el orden: el pod no espera a que el sidecar termine (nunca lo hará), sino a que esté iniciado —y a que pase su startupProbe si la tiene—. A diferencia de los init containers normales, los sidecars sí admiten sondas, tema de la lección 07-01.

Regla de decisión sencilla: si el contenedor auxiliar debe estar listo antes que la aplicación, o si el pod es de un Job, usa sidecar nativo. En los demás casos, un contenedor normal en containers sigue siendo perfectamente válido.

Los tres nombres vienen del artículo fundacional de Brendan Burns y Dave Oppenheimer sobre patrones de diseño para sistemas distribuidos. Se distinguen por hacia dónde va el flujo y qué transforman.

Otra forma de memorizarlo:

• El sidecar añade algo.
• El embajador simplifica lo que la aplicación ve del mundo exterior.
• El adaptador simplifica lo que el mundo exterior ve de la aplicación.

Los tres se apoyan en los mismos dos mecanismos, que ya conoces de 02-01:

• localhost compartido: todos los contenedores del pod comparten el espacio de nombres de red, así que se hablan por 127.0.0.1 sin pasar por la red del clúster, sin DNS y sin latencia apreciable. Corolario: dos contenedores del mismo pod no pueden usar el mismo puerto.
• Volúmenes compartidos: un emptyDir montado en ambos permite pasar ficheros. Es el canal del patrón adaptador.

La imagen postgres:16.4 no expone métricas en formato Prometheus. Modificarla sería un error: perderíamos las actualizaciones oficiales y tendríamos que mantener una imagen propia. La solución es un sidecar que se conecta a PostgreSQL por localhost, ejecuta consultas de estado y publica el resultado en /metrics.

Añadimos el sidecar al StatefulSet que construimos en 06-01:

Puntos que explican el patrón:

• DATA_SOURCE_URI: localhost:5432: no hay nombre de servicio ni DNS. El sidecar habla con PostgreSQL a través del bucle local del pod. Es la ventaja fundamental: latencia mínima, sin exponer el puerto 5432 a la red del clúster para esto, y sin necesidad de NetworkPolicy adicional, porque el tráfico ni siquiera sale del pod.
• Sidecar nativo: arranca antes que PostgreSQL. En principio no es imprescindible aquí, pero garantiza que no perdemos las métricas de los primeros segundos de vida, que son justo las del arranque y la recuperación del WAL.
• Recursos modestos y separados: 20m de CPU y 48 MiB. Se suman a los de PostgreSQL en el cálculo del scheduler.
• Endurecimiento propio: el sidecar corre como nobody y con sistema de ficheros de solo lectura. No necesita nada más, y así un fallo en el exportador no compromete al contenedor de la base de datos.

Nota importante sobre QoS: en 03-05 establecimos que postgres-reservas es de clase Guaranteed. Para que el pod siga siéndolo, todos sus contenedores —sidecar incluido— deben tener requests iguales a limits. Con los valores de arriba (20m/100m, 48Mi/96Mi) el pod pasaría a Burstable. Si queremos conservar Guaranteed, hay que igualarlos:

Es una consecuencia poco intuitiva de añadir sidecars que conviene tener presente.

El Service que expone las métricas:

Comprobación:

pg_up 1 confirma que el exportador puede conectar; numbackends da las conexiones activas. Estas métricas son las que Prometheus recogerá en la lección 07-03; aquí solo hemos montado la fuente.

api-reservas cobra a través de pagos.proveedorexterno.example, un servicio externo con las complicaciones habituales: TLS mutuo con certificado de cliente, reintentos con retroceso, cortacircuitos cuando el proveedor va lento, límite de peticiones por segundo y un endpoint de pruebas distinto en cada entorno.

Meter toda esa lógica en api-reservas significa escribirla en Node.js, mantenerla, probarla y volver a hacerla si mañana aparece un segundo proveedor. El embajador la saca del código: un proxy local que escucha en localhost y se ocupa de todo.

Y la configuración del proxy, resumida a lo esencial:

Lo que ha ganado Rutas Norte:

Y sobre todo: api-reservas hace un POST HTTP plano a http://127.0.0.1:8081/cobros y ya está. En las pruebas locales de desarrollo, ese endpoint puede ser un simulador; la aplicación no nota la diferencia.

La NetworkPolicy de 04-06 que autoriza la salida a la pasarela sigue aplicándose al pod, no al contenedor, así que no cambia: el pod entero necesita permiso de salida al puerto 443 externo.

Una aclaración necesaria: si esta idea se aplica a todo el tráfico de todos los pods, con un plano de control que distribuye la configuración, ya no se llama embajador sino malla de servicios (Istio, Linkerd). Ese es territorio de la lección 08-04; aquí resolvemos un caso concreto sin adoptar una plataforma entera.

worker-notificaciones es un componente heredado que escribe en un fichero, con un formato propio y con trazas multilínea cuando hay una excepción:

El recolector de logs del DaemonSet de 06-02 lee la salida estándar de los contenedores, no ficheros arbitrarios, y aunque los leyera, ese formato no es consultable: no hay campos, y una excepción se parte en tres entradas sin relación.

El adaptador resuelve las dos cosas: lee el fichero desde un volumen compartido, une las líneas de continuación y emite JSON estructurado por su propia salida estándar, donde el recolector sí lo recoge.

Resultado en la salida estándar del adaptador, que es lo que el recolector del nodo se lleva:

La excepción viaja entera en un solo registro, con sus campos separados y etiquetada con el componente y el entorno. En 07-05 esto permitirá consultas del tipo "todos los ENVIO_ERR de la reserva 4472".

Aquí el sidecar nativo aporta algo concreto e importante: como se termina después del contenedor principal, captura los últimos mensajes que worker-notificaciones escribe durante su cierre ordenado con SIGTERM (02-01). Con un contenedor normal en containers, ambos reciben SIGTERM a la vez y esas últimas líneas —a menudo las que explican por qué se paró— se pierden.

El sizeLimit: 256Mi del emptyDir no es opcional: un emptyDir sin límite escribe en el disco del nodo hasta llenarlo, y entonces el nodo entra en disk-pressure y desaloja pods ajenos.

Con init containers y sidecars nativos, el ciclo de vida de un pod queda así:

Puntos a retener:

1. Los init containers normales se ejecutan secuencialmente y hasta terminar.
2. Los sidecars nativos arrancan en el orden declarado, y basta con que estén iniciados.
3. Los contenedores principales arrancan todos a la vez, sin garantía de orden entre ellos.
4. En la terminación, primero los principales; después los sidecars, en orden inverso.
5. El terminationGracePeriodSeconds es del pod, no de cada contenedor: es el presupuesto total para todo el cierre.

Cada sidecar es un contenedor más por cada pod, y esa multiplicación es fácil de subestimar. Números de Rutas Norte en producción:

Medio núcleo y 600 MiB solo en contenedores auxiliares. En un pico de puente festivo, con api-reservas autoescalada a 20 réplicas (09-01), el embajador solo ya son 1 CPU y 1,25 GiB.

Y hay costes menos visibles:

• Cada sidecar es una imagen que hay que mantener, escanear y actualizar (08-05). Tres sidecars son tres cadenas de suministro más.
• Cada sidecar puede fallar y, con restartPolicy: Always, entrar en bucle de reinicio arrastrando al pod entero.
• Cada sidecar suma tiempo al arranque, y los nativos lo suman de forma secuencial antes de la aplicación.
• La depuración se complica: todo kubectl logs y kubectl exec necesita ya el flag -c.

Preguntas de control antes de añadir un sidecar:

1. ¿Puede hacerlo un DaemonSet, uno por nodo en lugar de uno por pod? Para logs y métricas de nodo, casi siempre sí.
2. ¿Puede hacerlo la propia aplicación con una librería? A veces cinco líneas de código sustituyen a un contenedor de 60 MiB.
3. ¿Justifica el sidecar su coste multiplicado por el número máximo de réplicas? Calcula el peor caso, no el habitual.

Olvidar -c <contenedor> en kubectl logs y kubectl exec. Con varios contenedores, kubectl exige saber cuál. El error a container name must be specified es inequívoco, pero cuando hay init containers el mensaje puede despistar porque el contenedor principal aún no existe.

Poner un init container en bucle infinito sin visibilidad. Un until ... done sin echo deja el pod en Init:0/1 sin ningún log que explique la espera. Imprime siempre algo en cada iteración.

Init containers pesados. El scheduler reserva el máximo entre los init containers, así que uno que pida 2 GiB obliga a encontrar un nodo con 2 GiB libres aunque la aplicación necesite 256 MiB. Mantenlos pequeños.

Migraciones en initContainer sin lock. Con N réplicas, la migración se ejecuta N veces, potencialmente en paralelo. Sin idempotencia y sin lock de aplicación, el resultado es una base de datos a medio migrar. Usa una herramienta de migraciones que tome lock, o un Job separado (06-03).

Dos contenedores del mismo pod escuchando en el mismo puerto. Comparten el espacio de red, así que el segundo falla con address already in use. Lleva un registro de qué puerto usa cada contenedor auxiliar (3000 la API, 8081 el embajador, 9187 el exportador...).

Sidecar clásico en un pod de Job. Es la trampa histórica: el Job no termina nunca. La solución en 1.29+ es un sidecar nativo con restartPolicy: Always como init container.

emptyDir sin sizeLimit para logs. Un log que crece sin control llena el disco del nodo y provoca disk-pressure, con desalojo de pods que no tenían nada que ver. Pon siempre sizeLimit.

Romper la clase QoS al añadir un sidecar. Un pod es Guaranteed solo si todos sus contenedores tienen requests == limits. Añadir un sidecar con valores distintos degrada el pod a Burstable y cambia su prioridad de desalojo (03-05).

Consejo: nombra los contenedores por su función, no por su tecnología. embajador-pagos es mucho más útil en una alerta a las tres de la mañana que envoy.

Consejo: kubectl describe pod es la mejor vista. Muestra Init Containers: y Containers: en bloques separados, con el estado, el código de salida y la razón de cada uno. Es más rápido que encadenar jsonpath.

Consejo: kubectl logs --all-containers=true vuelca todo el pod de golpe, útil para reconstruir la secuencia de un arranque problemático.

En rutas-norte-dev, crea un Deployment api-demo con una réplica de nginx:1.27.2-alpine y un init container que espere a que exista y responda un Service llamado dependencia-demo. Aplica el Deployment antes de crear la dependencia y observa el estado del pod. Después crea la dependencia (un Deployment y un Service con nginx) y comprueba que api-demo arranca.

En rutas-norte-dev, crea un Deployment worker-demo con:

• Un contenedor principal worker que cada 5 segundos escriba una línea en formato propietario en /logs/salida.log (por ejemplo 2026-08-05 10:00:00 | ENVIO_OK | reserva=4471).
• Un sidecar nativo adaptador (init container con restartPolicy: Always) que siga ese fichero y emita cada línea por su salida estándar con el prefijo [adaptado].
• Un emptyDir con sizeLimit: 64Mi compartido.

Verifica que el sidecar arranca antes que el principal y que emite las líneas.

Crea en rutas-norte-dev un Job informe-con-sidecar cuyo pod tenga un contenedor principal que tarde 15 segundos y termine, y un sidecar nativo que escriba algo cada 3 segundos indefinidamente. Comprueba que el Job sí llega a Complete. Después razona qué habría pasado si el sidecar estuviera declarado en containers en lugar de como init container con restartPolicy: Always.

Solución 1

Init:0/1: el init container está corriendo y ninguno ha completado.

Ahora la dependencia:

El pod pasó de Init:0/1 a PodInitializing y luego a Running sin ningún reinicio. Ese RESTARTS: 0 es la mejora frente a dejar que la aplicación entre en CrashLoopBackOff mientras espera.

Solución 2

La primera línea confirma el orden: el sidecar imprimió su mensaje de arranque antes de que el worker escribiera nada, porque los sidecars nativos arrancan antes que los contenedores de containers. El contenedor principal, en cambio, no imprime nada por su salida estándar:

Todo su registro va al fichero, y solo llega al recolector del nodo gracias al adaptador. Ese es exactamente el propósito del patrón.

Solución 3

El Job llega a Complete en 19 segundos pese a que el sidecar seguía imprimiendo latidos indefinidamente.

El pod está Completed con sus dos contenedores parados.

Qué habría pasado con el sidecar en containers: el contenedor generador habría terminado con éxito a los 15 segundos, pero metricas-lote habría seguido vivo. Un pod solo alcanza la fase Succeeded cuando todos sus contenedores han terminado, así que el pod se habría quedado indefinidamente en Running con 1/2 contenedores listos, y el Job en 0/1 completions para siempre. Solo activeDeadlineSeconds lo habría cortado, y con estado Failed.

Ese era exactamente el problema histórico que los sidecars nativos resolvieron.

Un pod con varios contenedores es una herramienta potente y fácil de usar mal. La regla que la gobierna es que los procesos compartan pod solo cuando estén tan acoplados que no tenga sentido escalarlos ni desplegarlos por separado, y cuando uno exista para servir al otro.

Los init containers se ejecutan en orden, hasta completarse, antes de que arranque ningún contenedor principal, y en Rutas Norte nos sirven para esperar a postgres-reservas, aplicar migraciones pequeñas e idempotentes, y preparar contenido en un emptyDir compartido. Sus estados —Init:0/2, Init:Error, Init:CrashLoopBackOff— son diagnósticos por sí mismos, y kubectl logs -c <nombre> es el comando que hay que interiorizar.

Los sidecars nativos de Kubernetes 1.29+ son init containers con restartPolicy: Always: arrancan antes que los contenedores principales, viven durante todo el pod, se reinician si mueren, se paran después de los principales y —lo que zanjó un problema de años— no impiden que un Job termine.

Los tres patrones clásicos se distinguen por la dirección del flujo: el sidecar añade una capacidad (el exportador de métricas de postgres-reservas que Prometheus consumirá en 07-03); el embajador intermedia la salida hacia el exterior (el proxy que se ocupa de TLS mutuo, reintentos y cortacircuito contra pagos.proveedorexterno.example); el adaptador normaliza lo que la aplicación produce (el conversor a JSON del log propietario de worker-notificaciones). Los tres se apoyan en localhost y en volúmenes compartidos, y los tres cuestan recursos multiplicados por el número de pods, algo que hay que calcular en el peor caso de escalado.

Hasta aquí hemos decidido qué se ejecuta y cómo se compone cada pod. La pregunta que no hemos tocado es dónde: hasta ahora el kube-scheduler ha colocado nuestros pods donde ha querido, y eso ha bastado. Pero postgres-reservas debería estar en un nodo con disco SSD, las réplicas de api-reservas no deberían compartir nodo —si ese nodo cae, se cae la API entera—, y las cargas de análisis no deberían competir con la venta de billetes. Todo eso se controla con afinidad, taints y tolerations, y es el tema de la siguiente lección: Planificación.