Tienes los conceptos y un clúster kind con un Redis suelto. Ahora va la plataforma entera: los cuatro servicios de Aurora Libros con manifiestos reales, las sondas de 06-01, el endurecimiento de 05-03 y la imagen que publicó tu pipeline en 06-02. Al final, /libros devolverá los nueve títulos desde dentro del clúster.

1. Organización de k8s/ y el Namespace
2. aurora-cache: Deployment y Service
3. Por qué aurora-db es un StatefulSet
4. El StatefulSet con volumeClaimTemplates
5. Service headless y el ConfigMap con init.sql
6. aurora-api: imagen por digest e imagePullSecrets
7. Las tres sondas en el manifiesto
8. requests, limits y las clases de QoS
9. securityContext de Pod y de contenedor
10. Configuración con ConfigMap y Secret
11. aurora-web: Deployment, Service e Ingress
12. TLS con cert-manager
13. Kustomize: bases y overlays por entorno
14. Puesta en marcha y verificación
15. Depuración: los estados de un Pod
16. Helm como alternativa

Un fichero por servicio, con todos sus objetos juntos separados por ---. Es más práctico que un fichero por objeto: para entender aurora-api abres un único fichero y ves su Deployment, su Service y su configuración. El primero es el Namespace, un objeto de cinco líneas (apiVersion: v1, kind: Namespace, metadata.name: aurora) que crea la partición donde vivirá todo lo demás.

Dos patrones que se repetirán en todos los manifiestos. El primero: los puertos se nombran (name: redis) y luego se referencian por nombre en el Service y en las sondas; si algún día cambias el número, lo cambias en un solo sitio. El segundo: la etiqueta app.kubernetes.io/name es la única que aparece en el selector, y las demás quedan fuera de él, porque el selector es inmutable y no conviene atarlo a nada que vaya a cambiar. Y fíjate en que Redis es aquí una caché desechable: sin volumen y sin persistencia, porque si el Pod muere la API vuelve a servir con origen: db hasta que se recalienta, que es exactamente lo que decidiste en la sonda de readiness de 06-01.

Un Deployment con un volumen para PostgreSQL falla por dos motivos. Primero, la estrategia por defecto arranca el Pod nuevo antes de matar el viejo: durante unos segundos habría dos PostgreSQL escribiendo sobre los mismos ficheros, lo que corrompe los datos. Segundo, si escalaras a dos réplicas, ambas compartirían el mismo PVC —o se pelearían por él— sin ninguna coordinación.

Advertencia. Ejecutar una base de datos en Kubernetes es factible, pero en producción exige un operador (CloudNativePG, Zalando Postgres Operator, Crunchy) que gestione failover, copias, replicación y actualizaciones de versión, o directamente un servicio gestionado fuera del clúster. Un StatefulSet a pelo como el de esta lección es correcto para aprender y para entornos de desarrollo, pero no cubre la recuperación ante desastres. Valida esta decisión con el responsable de infraestructura y de datos de tu organización antes de poner datos reales.

El PGDATA en un subdirectorio no es un capricho: muchos aprovisionadores crean un lost+found en la raíz del volumen y PostgreSQL se niega a inicializarse en un directorio que no esté vacío. Usar /data/pgdata evita ese fallo, que es de los que cuestan una tarde entera. Por su parte, el volumeClaimTemplates genera un PVC llamado datos-aurora-db-0, con una propiedad deliberada: borrar el StatefulSet no borra sus PVC. Es una red de seguridad —los datos sobreviven a un borrado accidental— y también una fuente de sorpresas, porque recrear el StatefulSet reengancha el volumen anterior con todo lo que hubiera dentro.

Un Service normal reparte entre Pods, que es justo lo que no quieres con una base de datos: cada réplica es distinta y tienes que poder dirigirte a una concreta. Con clusterIP: None, el DNS devuelve directamente las direcciones de los Pods, y cada uno recibe además su nombre estable: aurora-db-0.aurora-db.aurora.svc.cluster.local. Con réplicas de lectura, ese nombre es el que te permite apuntar las escrituras al primario.

El init.sql con los nueve títulos entra como ConfigMap generado desde el fichero, con kubectl create configmap aurora-init-sql --from-file=init.sql=db/init.sql -n aurora. Un límite que conviene conocer: un ConfigMap no puede pasar de 1 MiB, porque vive en etcd. Para un init.sql de nueve libros sobra, pero un volcado real no cabe; en ese caso se usa un initContainer que lo descargue de un almacenamiento de objetos.

Fijar el digest junto a la etiqueta es lo que hace que el despliegue sea inmutable de verdad: la etiqueta documenta qué versión es y el digest garantiza qué bytes se ejecutan, aunque alguien haya movido 2.0.0 en el registro. Es la práctica que exige cualquier política de admisión seria. Sobre imagePullPolicy hay una trampa clásica: con la etiqueta latest el valor por defecto es Always, y con cualquier otra es IfNotPresent; fijando el digest, IfNotPresent es correcto y evita descargas innecesarias, porque un digest siempre identifica el mismo contenido.

Los números están elegidos con una lógica: la readiness reacciona rápido (10 s) porque su consecuencia es barata y reversible —dejar de mandar tráfico—, mientras que la liveness reacciona despacio (45 s) porque su consecuencia es cara y disruptiva —matar el proceso—. Invertir esos plazos es la receta de los reinicios en cascada bajo carga. Y el preStop con sleep 5 cumple aquí el mismo papel que la espera de cinco segundos que programaste en 06-01: cuando Kubernetes decide terminar un Pod, elimina su endpoint y manda SIGTERM a la vez, y esas dos cosas se propagan a ritmos distintos por todos los kube-proxy del clúster. El sleep retrasa el SIGTERM lo justo para que las tablas de enrutado se actualicen antes.

Para aurora-api, requests: { memory: 128Mi, cpu: 100m } y limits: { memory: 512Mi, cpu: "1" }. Los dos campos hacen cosas distintas:

aurora-api queda como Burstable, que es lo correcto para una API: reserva poco para que quepan muchas réplicas por nodo y puede subir hasta el límite en los picos. aurora-db, en cambio, es candidata a Guaranteed en producción, porque no quieres que el kernel elija a tu base de datos cuando haya que expulsar algo. Los números salen directamente de la tabla de docker stats de 06-01: 214 MiB de pico → límite de 512 MiB.

Esto es, línea por línea, la traducción del endurecimiento del compose.prod.yaml de 05-03. La única novedad es runAsNonRoot: true, que merece atención: no cambia el usuario, sino que verifica que la imagen no arranque como root, y si lo hace el Pod falla al crearse con CreateContainerConfigError. Es una comprobación barata que impide que una imagen mal construida llegue a ejecutarse. Y fsGroup resuelve el problema clásico de permisos con volúmenes: Kubernetes cambia el grupo propietario del contenido montado a ese GID, de modo que un proceso sin privilegios puede escribir en su PVC.

La API no necesita ni una línea de cambio: los mismos nombres de variable que definiste en config.js en 06-01 llegan ahora desde un ConfigMap en vez de desde Compose, que es la recompensa de haber sacado toda la configuración de la imagen. Podrías además montar el secreto como fichero y usar DB_PASSWORD_FILE, más seguro por lo que viste en 06-03 sobre la herencia a subprocesos; aquí se usa secretKeyRef por brevedad, pero en producción el volumen es preferible y tu código ya lo soporta.

Un detalle operativo importante: cambiar un ConfigMap no reinicia los Pods. Para aplicar el cambio hay que forzarlo con kubectl rollout restart deployment/aurora-api, o dejar que Kustomize genere el ConfigMap con un sufijo de hash, que es lo que haremos.

Fíjate en el cambio de arquitectura: en Compose, aurora-web hacía de proxy inverso hacia la API. Aquí ese trabajo lo hace el Ingress, y Nginx queda reducido a servir ficheros estáticos. Es lo natural en Kubernetes: el enrutado es responsabilidad de la plataforma, no de tu contenedor, y así puedes escalar el frontal y la API por separado.

Con cert-manager instalado y un ClusterIssuer configurado, esas cinco líneas bastan: el operador ve la anotación, solicita el certificado a Let's Encrypt, resuelve el desafío ACME, guarda el resultado en el Secret aurora-tls y lo renueva automáticamente antes de que caduque. Es el ejemplo canónico de operador y de lo que Kubernetes añade sobre Swarm: una tarea recurrente que alguien hacía a mano se convierte en un controlador más. La configuración del emisor —producción o staging de Let's Encrypt, DNS-01 frente a HTTP-01— es una decisión de plataforma que conviene acordar con tu equipo de infraestructura.

Kustomize es la misma idea de los overrides de Compose de 04-06, con la diferencia de que aquí forma parte de kubectl: una base común y overlays que la parchean por entorno, sin duplicar ni un fichero ni usar plantillas.

El configMapGenerator resuelve el problema del final de la sección 10: genera el ConfigMap con un sufijo derivado del hash del contenido (aurora-init-sql-7f9c2d) y actualiza automáticamente la referencia en los Deployments. Como el nombre cambia, la plantilla del Pod cambia, y el despliegue progresivo se dispara solo cuando editas la configuración. Es exactamente el comportamiento que quieres y que a mano nunca ocurre.

El aurora-db-0 con su ordinal y el CLUSTER-IP None del Service headless confirman que el StatefulSet está bien montado.

Los nueve títulos están ahí, y la segunda llamada devuelve origen: cache: el cache-aside funciona exactamente igual que en tu portátil, ahora repartido entre tres Pods de API que hablan con un Redis y un PostgreSQL por sus Services. La aplicación no ha cambiado ni una línea desde el módulo 4.

kubectl debug resuelve el problema que tenías con las imágenes mínimas de 05-03: adjunta un contenedor efímero con todas las herramientas al Pod ya en marcha, compartiendo su red y sus namespaces, sin reiniciar nada y sin necesidad de que la imagen contenga un sh. Es el netshoot del módulo 3, aplicado al mundo de Kubernetes.

La combinación habitual es usar Helm para el software de terceros —ingress-nginx, cert-manager, Prometheus— y Kustomize para lo tuyo, que es lo que hace Aurora Libros. Helm brilla cuando quieres distribuir tu aplicación a terceros que necesitan parametrizarla; para una aplicación propia con dos entornos, Kustomize evita convertir tus manifiestos en plantillas ilegibles.

• Una base de datos en un Deployment. Durante la actualización conviven dos Pods escribiendo sobre el mismo disco. StatefulSet con stop-first, y en producción un operador.
• Olvidar imagePullSecrets. ImagePullBackOff en todos los Pods con un registro privado. El secreto es por namespace.
• PGDATA en la raíz del volumen. El lost+found del aprovisionador impide inicializar PostgreSQL.
• Liveness apuntando a /salud/listo. Reinicios en cascada cuando la base de datos tose. La liveness solo mira el proceso.
• initialDelaySeconds corto sin startupProbe. El Pod se reinicia antes de terminar de arrancar, para siempre.
• Editar un ConfigMap y esperar que se aplique. No reinicia nada: rollout restart o configMapGenerator.
• Consejo: kubectl apply -k --dry-run=server en el pipeline valida los manifiestos contra la API real antes de tocar el clúster, y kubectl rollout restart deployment/... es la forma correcta de "reiniciar" (no delete pod).
• Consejo: kubectl get events --sort-by=.lastTimestamp es la vista más útil cuando algo falla y no sabes ni qué objeto mirar.

Ejercicio 1. Despliega Aurora Libros completa en tu clúster kind y verifica de extremo a extremo: que aurora-db-0 tiene su PVC enlazado, que /libros devuelve los nueve títulos y que la segunda llamada viene de la caché.

Ejercicio 2. Diagnostica tres fallos provocados sin mirar los manifiestos: un Pending por requests imposibles, un ImagePullBackOff y un CrashLoopBackOff por falta de una variable obligatoria. Indica en cada caso qué comando lo revela.

Ejercicio 3. Demuestra que el StatefulSet conserva la identidad y los datos: escribe un registro en la base, borra el Pod aurora-db-0 y comprueba qué sobrevive y qué no.

Solución 1.

El nombre datos-aurora-db-0 es la firma del volumeClaimTemplates: <nombre-de-la-plantilla>-<nombre-del-statefulset>-<ordinal>. Si escalaras a dos réplicas aparecería datos-aurora-db-1, con su propio disco, que es justo lo que un Deployment no puede darte.

La verificación de extremo a extremo está completa: el ConfigMap con init.sql se ejecutó al inicializar PostgreSQL, los nueve títulos están en la tabla, y la API los sirve desde la base de datos la primera vez y desde Redis la segunda. Pero merece la pena detenerse en lo que no ha hecho falta. No has tocado el código de la aplicación, ni el Dockerfile, ni las variables que espera. La imagen que ejecuta el clúster es la misma que construyó el pipeline de 06-02 y la misma que corría en tu Compose: el contrato que estableciste en 06-01 —configuración por entorno, sondas separadas, apagado ordenado— es el que ha permitido que cambiar de plataforma sea solo cambiar quién inyecta las variables.

Solución 2.

La regla de diagnóstico que resume la tabla es la que ahorra más tiempo en Kubernetes: si el contenedor nunca llegó a arrancar, la respuesta está en los eventos; si arrancó y murió, está en los logs. En los dos primeros casos kubectl logs no devuelve nada, y no porque falle, sino porque no hay proceso que haya escrito nada. En el tercero, describe solo dice Back-off restarting failed container, que no explica nada; el --previous es imprescindible porque el contenedor actual acaba de nacer y el que falló ya no existe. Y fíjate en la calidad de ese tercer mensaje: dice exactamente qué variable falta, que es el rendimiento del config.js de 06-01 en un entorno donde depurar es mucho más incómodo.

Solución 3.

El contraste con el ejercicio 2 de 06-04 es el punto de la lección. Allí, al borrar un Pod de un Deployment volvía otro Pod con otro nombre; aquí vuelve aurora-db-0, el mismo nombre, el mismo DNS y, sobre todo, el mismo disco, con el décimo libro dentro. Que la IP cambie y no pase nada demuestra por qué la base de datos se referencia siempre por su nombre DNS y nunca por dirección: aurora-db en el ConfigMap sigue resolviendo, así que las tres réplicas de la API se reconectaron solas —con el reintento con backoff de 04-04— sin que tocaras nada.

Ahora la advertencia que este ejercicio no demuestra y conviene no olvidar: has sobrevivido a la muerte de un Pod, no a la de un nodo ni a la de un disco. Con ReadWriteOnce, si el nodo que aloja el PVC queda inaccesible, el Pod puede quedarse en Pending hasta que el volumen se libere. Eso, y la ausencia de failover automático, es exactamente lo que aporta un operador de PostgreSQL y lo que hay que resolver antes de poner datos de clientes aquí.

Aurora Libros entera vive en Kubernetes. Has escrito los manifiestos de los cuatro servicios con criterio: aurora-cache como Deployment desechable con puertos nombrados, aurora-db como StatefulSet —con el porqué claro: dos PostgreSQL sobre los mismos ficheros corrompen los datos— con sus volumeClaimTemplates, su Service headless, su ConfigMap con los nueve títulos y el PGDATA en un subdirectorio para esquivar el lost+found. Y con la advertencia en su sitio: esto sirve para aprender, pero producción pide un operador o una base gestionada, validado con tu equipo de infraestructura.

El Deployment de aurora-api recoge todo lo del módulo: la imagen del pipeline fijada por digest con su imagePullSecrets, las tres sondas de 06-01 apuntando a /salud/arrancado, /salud/vivo y /salud/listo con plazos asimétricos a propósito —readiness rápida porque es barata, liveness lenta porque mata—, el preStop que compra los segundos que necesita el kube-proxy, las requests y limits sacados de la medición real con su clase de QoS, y el securityContext que traduce línea a línea el endurecimiento de 05-03. La configuración entra por ConfigMap y Secret sin tocar una línea de la aplicación, que es la recompensa de haberla sacado de la imagen. aurora-web queda como servidor estático y el enrutado pasa al Ingress, con cert-manager renovando el TLS solo.

Todo se aplica con kubectl apply -k y Kustomize, con una base y overlays por entorno, y el configMapGenerator que dispara el despliegue progresivo cuando cambia la configuración. Has verificado que /libros devuelve los nueve títulos con origen: db y cache en la segunda llamada, sabes leer la tabla de estados de un Pod con la regla que más tiempo ahorra —si nunca arrancó, mira los eventos; si arrancó y murió, mira los logs con --previous—, tienes kubectl debug para inspeccionar imágenes sin shell, y sabes cuándo usar Helm y cuándo Kustomize.

En la siguiente lección, Escalado y Balanceo de Carga, la plataforma aprende a crecer. Verás por qué la API escala replicando y la base de datos no, cómo balancean de verdad kube-proxy y el Ingress, y montarás un HorizontalPodAutoscaler sobre aurora-api que crea réplicas solo mientras generas carga real contra /libros, midiendo la latencia antes y después para saber dónde está el cuello de botella.