Cómo depurar despliegues bloqueados en Kubernetes: Diagnóstico de fallos en Deployments

Un tutorial publicado por freeCodeCamp detalla cómo diagnosticar y depurar iteraciones de despliegues (rollouts) bloqueadas en Kubernetes dentro de un entorno local con kind. La guía práctica se centra en investigar aquellos casos en los que las actualizaciones se agotan por tiempo mientras los Pods existentes siguen respondiendo al tráfico entrante del Service.

Aislamiento de fallos comunes en despliegues

La guía describe tres escenarios de fallo habituales: etiquetas de imagen de contenedor inexistentes, pruebas de disponibilidad (readiness probes) defectuosas y selectores de nodos no satisfechos. En un fallo de descarga de imagen, los contenedores permanecen en estado ImagePullBackOff con una fase de Pod en Pending. Por su parte, los fallos en las pruebas de disponibilidad dejan los contenedores en ejecución pero marcados como no listos tras devolver errores HTTP como 404. Finalmente, las restricciones de ubicación impiden que los Pods se asignen a algún nodo, dejándolos en estado Pending sin iniciar la configuración del contenedor.

Rastreo de propiedad y estado del controlador

Diagnosticar un despliegue atascado requiere rastrear la propiedad de los objetos desde el Deployment hasta sus ReplicaSets activos y nuevos, llegando hasta los Pods individuales mediante metadatos de UID. Al comparar metadata.generation con status.observedGeneration se revela si el controlador ha procesado la actualización de especificación deseada. Los eventos detallados de ejecución recuperados mediante selectores de campo permiten precisar por qué un Pod de reemplazo no logra estar listo.

Diferenciación de tiempos de espera y disponibilidad de endpoints

El tutorial destaca la diferencia operativa entre un tiempo de espera del lado del cliente desde comandos como kubectl rollout status y el plazo límite de progreso del controlador de Deployment regulado por progressDeadlineSeconds. Cuando el progreso falla, el controlador actualiza las condiciones de estado a Progressing=False con el motivo ProgressDeadlineExceeded, sin revertir los cambios de forma automática. A lo largo de estos fallos, Kubernetes mantiene las réplicas saludables de la revisión anterior en los EndpointSlices, lo que garantiza un tráfico de red sin interrupciones hasta que los Pods de reemplazo cumplan los requisitos de disponibilidad.

Ilustración editorial generada con IA; no es una fotografía documental.

Fuente: How to Debug a Stuck Kubernetes Rollout with a Hands-On Lab