Depurar una aplicación
Cuando la aplicación arranca pero no hace lo que debe, hay que acercarse a ella: leer lo que dice, entrar dentro, hablarle directamente o volver a la versión anterior.
Del clúster a la aplicación
En la lección 10 viste qué hacer cuando un Pod no llega a funcionar: estados, motivos y eventos. Esta lección empieza donde acaba aquella. El Pod está en Running, Kubernetes dice que todo va bien… pero la web da errores, va lenta o no responde. Ahora toca mirar dentro de la aplicación.
Piensa en un mecánico ante un coche que arranca pero hace un ruido raro. Primero escucha (los logs). Luego abre el capó (entrar en el contenedor). Si hace falta, conecta su máquina de diagnóstico (un contenedor de depuración). Prueba el coche en el taller, sin salir a la calle (port-forward). Y si la avería vino con la última reparación, deshace ese cambio (rollback).
- logs
- Lee los mensajes que escribe la aplicación. Sólo mira, no cambia nada.
- exec
- Ejecuta una orden dentro de un contenedor que ya está en marcha, como abrir un terminal en él.
- debug
- Añade al Pod un contenedor temporal con herramientas de diagnóstico, para cuando la imagen no las trae.
- port-forward
- Abre un túnel desde tu ordenador hasta un Pod para probarlo directamente, sin pasar por la red pública.
- rollout undo
- Vuelve el Deployment a su versión anterior. Es el botón de deshacer.
Escuchar: kubectl logs
Las aplicaciones en contenedores escriben sus mensajes por pantalla (lo que en informática se llama salida estándar). Kubernetes guarda esa salida y la puedes leer con kubectl logs. Es siempre lo primero que se mira.
| Comando | Qué hace |
|---|---|
| kubectl logs tienda-7d9f | Muestra los mensajes del contenedor del Pod. |
| kubectl logs -f tienda-7d9f | Los sigue en directo, según van saliendo (-f viene de follow). |
| kubectl logs --previous tienda-7d9f | Los del contenedor anterior, el que se cayó. Imprescindible cuando se reinicia en bucle. |
| kubectl logs tienda-7d9f -c ayudante | Los de un contenedor concreto, cuando el Pod tiene varios (-c de container). |
Si un contenedor se ha reiniciado, kubectl logs a secas te enseña los mensajes del contenedor nuevo, que acaba de arrancar y aún no ha fallado. Para ver por qué se cayó el anterior hace falta --previous.
Abrir el capó: kubectl exec
Con kubectl exec ejecutas un comando dentro de un contenedor que ya está en marcha. Sirve para comprobar cosas desde dentro: si un fichero de configuración tiene lo que esperas, si desde ahí se llega a la base de datos, qué variables de entorno tiene.
# Ver las variables de entorno del contenedor kubectl exec tienda-7d9f -- env # Abrir una terminal dentro del contenedor (-it = interactivo) kubectl exec -it tienda-7d9f -- sh
Las dos rayas -- separan lo que es de kubectl de lo que es el comando que quieres ejecutar dentro.
Cuando no hay nada dentro: kubectl debug
Hay un problema con exec: sólo puedes usar las herramientas que ya traiga la imagen. Y cada vez más imágenes vienen casi vacías a propósito: sólo la aplicación, sin terminal ni utilidades. Se llaman imágenes mínimas o distroless. Son más pequeñas y más seguras (un atacante que entre no encuentra herramientas), pero también un fastidio para depurar: kubectl exec -it … -- sh falla porque no hay sh.
La solución es kubectl debug, que añade al Pod un contenedor efímero (ephemeral container): un contenedor temporal, con la imagen que tú elijas y todas sus herramientas, que se mete en el Pod sin reiniciarlo.
Es como llamar a un técnico que viene con su propia caja de herramientas. La cocina del cliente no tiene destornilladores, pero da igual: el técnico trae los suyos, entra, revisa, y se va sin dejar nada.
- kubectl debug
- La orden que añade un contenedor de depuración a un Pod que ya existe.
- --image=busybox
- Indica qué imagen usar para ese contenedor. busybox es una imagen mínima con utilidades básicas.
- Distroless
- Una imagen que sólo trae la aplicación, sin terminal ni utilidades. Es más segura y ligera, pero no se puede entrar con exec.
- Contenedor efímero
- Un contenedor temporal que se añade a un Pod en marcha sólo para investigar. No se reinicia y no forma parte de la definición del Pod.
- sh · curl · ping
- Herramientas de diagnóstico: un terminal para escribir órdenes, una para hacer peticiones web y otra para comprobar si algo responde por la red.
# Meter un contenedor con herramientas en el Pod, apuntando al contenedor «app» kubectl debug -it tienda-7d9f --image=busybox --target=app
Un contenedor efímero no se puede quitar del Pod una vez añadido, aunque termine. Desaparece cuando se borra el Pod. Tampoco puede tener puertos ni sondas: sirve sólo para investigar, nunca para dar servicio.
kubectl debug también puede crear una copia del Pod para investigar sin tocar el original, o abrir una sesión en un nodo.
Hablarle directamente: kubectl port-forward
A veces quieres probar la aplicación tú mismo, desde tu navegador, sin pasar por el Service, el Ingress ni nada de lo que hay delante. kubectl port-forward abre un túnel desde un puerto de tu ordenador hasta un puerto del Pod.
- localhost:8080
- Una dirección de tu propio ordenador. Al abrirla en el navegador, el tráfico viaja por el túnel hasta el Pod.
- API server y kubelet
- Las piezas de Kubernetes por las que pasa el túnel: la puerta de entrada del clúster y el encargado del nodo.
- Puerto 80
- La «puerta» por la que escucha la aplicación dentro del Pod.
- 8080:80
- Cómo se escribe el túnel: el primer número es el puerto de tu ordenador y el segundo, el del Pod.
Los clientes dicen que la tienda da error, pero no sabes si el fallo está en la aplicación o en lo que hay delante (el Ingress, el balanceador). Haces kubectl port-forward pod/tienda-7d9f 8080:80 y abres http://localhost:8080 en tu navegador.
Si así funciona, la aplicación está bien y el problema está en el camino. Si falla igual, el problema está en la aplicación.
El tráfico no llega: revisar el Service
Un caso muy frecuente: los Pods funcionan, el port-forward también, pero a través del Service no llega nada. Recuerda que un Service encuentra sus Pods con un selector de etiquetas (lección 03) y sólo manda tráfico a los Pods que están listos (la readinessProbe de la lección 10). La lista de Pods a los que reparte se guarda en unos objetos llamados EndpointSlices.
- Service
- La dirección fija de una aplicación. Busca sus Pods por etiquetas y les reparte el tráfico.
- Pod
- Una copia de la aplicación en marcha.
- app: tienda
- Una etiqueta (label): un par nombre y valor que se pega a los objetos para poder encontrarlos y agruparlos.
- Endpoints · EndpointSlices
- La lista de direcciones de los Pods a los que un Service manda tráfico. Si está vacía, el Service no tiene a quién mandarlo.
Si el Service no tiene endpoints, hay dos sospechosos:
- El selector no coincide con las etiquetas de los Pods: compara kubectl describe service tienda con kubectl get pods --show-labels.
- Los Pods no están listos: su readinessProbe falla y el Service los aparta. Lo ves en la columna READY (0/1).
Si sí hay endpoints, revisa que el puerto del Service (targetPort) sea el mismo en el que escucha la aplicación.
Cuánto gasta: kubectl top
Cuando la aplicación va lenta, conviene saber cuánta CPU y memoria está usando de verdad. kubectl top pods y kubectl top nodes lo muestran.
$ kubectl top pods
NAME CPU(cores) MEMORY(bytes)
tienda-7d9f8c6b5-2xkqp 480m 410Mi
pedidos-5b4c7f9d8-mn4lw 12m 95Mi
kubectl top sólo funciona si el clúster tiene instalado el metrics-server, un complemento que recoge el consumo de cada Pod y nodo. Sin él, el comando da error. Es el mismo componente del que tira el autoescalado horizontal (HPA) de la lección 05.
Deshacer: kubectl rollout
Muchas veces la aplicación empieza a fallar justo después de sacar una versión nueva. Un Deployment guarda el historial de sus versiones (cada versión es una revisión), así que volver atrás es un solo comando. En la lección 11 viste cómo se sacan versiones nuevas; aquí, cómo vigilarlas y deshacerlas.
- Revisión
- Cada versión guardada en el historial del Deployment. Se crea una nueva cada vez que cambias su plantilla, por ejemplo la imagen.
- tienda:1.0
- El nombre y la versión de la imagen que usa cada revisión.
- kubectl rollout undo
- Vuelve a la revisión anterior. En el historial aparece como una revisión nueva con el contenido de la vieja.
| Comando | Qué hace |
|---|---|
| kubectl rollout status deployment/tienda | Sigue el despliegue en curso y dice cuándo ha terminado o si se ha atascado. |
| kubectl rollout history deployment/tienda | Lista las revisiones guardadas. |
| kubectl rollout undo deployment/tienda | Vuelve a la revisión anterior. |
| kubectl rollout undo deployment/tienda --to-revision=1 | Vuelve a una revisión concreta. |
Si trabajas con GitOps (lección 11), el rollback de verdad se hace en Git, volviendo atrás el cambio. Si haces rollout undo a mano, la herramienta de GitOps verá que el clúster no coincide con Git y lo volverá a dejar como dice Git.
Resumen en cinco frases
- kubectl logs es lo primero; con --previous ves los mensajes del contenedor que se cayó y con -c eliges contenedor.
- kubectl exec ejecuta comandos dentro de un contenedor en marcha, pero sólo con lo que trae su imagen.
- kubectl debug añade un contenedor efímero con herramientas, ideal para imágenes distroless, sin reiniciar el Pod.
- kubectl port-forward te deja hablar directamente con un Pod; si el Service no llega, revisa sus endpoints, el selector y la readiness.
- kubectl top necesita metrics-server, y kubectl rollout undo vuelve a la versión anterior de un Deployment.
Términos del examen
- kubectl logs
- Muestra los mensajes que ha escrito un contenedor.
- --previous
- Opción de logs para ver el contenedor anterior, el que se reinició.
- kubectl exec
- Ejecuta un comando dentro de un contenedor en marcha.
- kubectl debug
- Añade un contenedor de depuración a un Pod, crea una copia del Pod o abre sesión en un nodo.
- Ephemeral container
- Contenedor temporal que se añade a un Pod existente para investigar. No tiene puertos ni sondas.
- Distroless
- Imagen mínima con sólo la aplicación, sin terminal ni utilidades.
- kubectl port-forward
- Túnel desde un puerto de tu ordenador hasta un Pod o Service.
- EndpointSlice
- Lista de las IP de los Pods listos a los que un Service reparte tráfico.
- Selector
- Las etiquetas que un Service usa para encontrar sus Pods.
- targetPort
- El puerto del contenedor al que el Service manda el tráfico.
- kubectl top
- Muestra el consumo real de CPU y memoria de Pods y nodos.
- metrics-server
- Complemento que recoge el consumo de recursos. Lo necesitan kubectl top y el HPA.
- Revision
- Cada versión guardada de un Deployment.
- kubectl rollout
- Comandos para seguir (status), consultar (history) y deshacer (undo) despliegues.
Comprueba que lo has entendido
1. A container keeps restarting. Which command shows the logs of the container instance that crashed?
- kubectl logs <pod>
- kubectl logs <pod> --previous
- kubectl describe node
- kubectl get events --all-namespaces
Ver respuesta
B. Sin --previous ves los mensajes del contenedor nuevo, que aún no ha fallado. Con --previous ves los del que se cayó.
2. You need to troubleshoot a running Pod whose image is distroless and has no shell. What is the best option?
- kubectl exec -it <pod> -- sh
- Rebuild the image with debugging tools and redeploy
- kubectl debug to add an ephemeral container with the tools you need
- kubectl port-forward to the Pod
Ver respuesta
C. kubectl debug añade un contenedor efímero con sus propias herramientas al Pod que ya está en marcha, sin reiniciarlo. exec fallaría porque no hay terminal en la imagen.
3. Which command lets you access a Pod's port from your local machine without exposing it through a Service?
- kubectl expose
- kubectl port-forward
- kubectl proxy-pod
- kubectl attach
Ver respuesta
B. port-forward abre un túnel temporal desde un puerto de tu ordenador hasta el Pod. kubectl expose crea un Service, justo lo que la pregunta quiere evitar. proxy-pod no existe.
4. Running "kubectl top pods" returns an error saying metrics are not available. What is the most likely cause?
- The Pods have no resource limits
- metrics-server is not installed in the cluster
- The kube-scheduler is down
- The Pods are in a different namespace
Ver respuesta
B. kubectl top lee los datos del metrics-server. Si no está instalado, no hay métricas que mostrar.
5. After updating a Deployment, the new version has a bug. Which command returns the Deployment to its previous revision?
- kubectl rollout undo deployment/<name>
- kubectl rollout status deployment/<name>
- kubectl delete deployment <name>
- kubectl rollout pause deployment/<name>
Ver respuesta
A. rollout undo vuelve a la revisión anterior. status sólo informa, pause detiene el despliegue sin deshacerlo y borrar el Deployment tiraría la aplicación.