Depuración de despliegues fallidos: Identificación de errores comunes de YAML y configuración

El despliegue de aplicaciones en Kubernetes a menudo se optimiza mediante una configuración declarativa gestionada a través de manifiestos YAML. Sin embargo, cuando los despliegues no logran alcanzar el estado deseado —quedándose atascados en Pending, ImagePullBackOff o fallando abruptamente— la causa principal es frecuentemente un error sutil dentro de estos archivos de configuración o en los recursos subyacentes del clúster. Esta guía proporciona un enfoque sistemático para diagnosticar y resolver los escollos comunes de YAML y configuración que afectan a los despliegues de Kubernetes.

Comprender cómo interpretar los eventos de Kubernetes e inspeccionar el estado de los recursos es crucial para una depuración eficiente. Este artículo le guiará a través de los comandos y comprobaciones esenciales necesarios para mover rápidamente sus despliegues fallidos a un estado saludable y en funcionamiento, centrándose en errores de sintaxis, restricciones de recursos y problemas de configuración de red.

Los primeros pasos: Comprobación del estado y los eventos del despliegue

Cuando un despliegue falla, sus primeros pasos de diagnóstico siempre deben implicar la comprobación del propio recurso primario y los eventos asociados con sus ReplicaSets y Pods gestionados. Esto proporciona la vista de más alto nivel de lo que Kubernetes está intentando hacer y por qué está fallando.

1. Inspección del estado del despliegue

Utilice kubectl get deployments para ver el estado general. Fíjese específicamente en las columnas READY, UP-TO-DATE y AVAILABLE. Una discrepancia aquí indica un problema con los Pods subyacentes.

kubectl get deployments <deployment-name>

Si el estado del despliegue muestra pocas o cero réplicas listas, proceda a verificar el ReplicaSet.

2. Revisión de eventos de ReplicaSet y Pod

Los ReplicaSets gestionan el número deseado de Pods. Si el despliegue falla, el ReplicaSet suele ser la fuente de la cascada de errores. Utilice el comando describe en el ReplicaSet, que generalmente se llama <nombre-del-despliegue>-<hash>:

kubectl describe rs <nombre-del-replicaset>

Fundamentalmente, examine la sección Events (Eventos) en la parte inferior de la salida. Esta sección detalla las acciones recientes, incluidos los intentos de planificación, los fallos de extracción de imágenes y los problemas de montaje de volúmenes. Estos eventos suelen ser la prueba irrefutable.

Finalmente, compruebe los propios Pods, ya que informan del fallo inmediato:

kubectl get pods -l app=<etiqueta-de-su-app>
kubectl describe pod <nombre-del-pod>

Busque los campos State (Estado) y Reason (Motivo) en la descripción del pod. Los motivos comunes incluyen ImagePullBackOff, ErrImagePull, CrashLoopBackOff y Pending.

Errores de configuración comunes en manifiestos YAML

Las configuraciones incorrectas en sus archivos YAML son la causa más frecuente de fallos en el despliegue. Estos errores pueden ir desde simples errores de sangría hasta complejos problemas estructurales.

1. Errores de sintaxis y estructura de YAML

Las APIs de Kubernetes son extremadamente sensibles a la sintaxis correcta de YAML (sangría, espaciado y tipos de datos). Si el YAML no es válido, kubectl apply a menudo fallará inmediatamente, indicando que no puede analizar el archivo.

Mejor práctica: Utilizar un Linter
Valide siempre su sintaxis YAML antes de aplicar. Herramientas como yamllint o el soporte integrado en el IDE pueden detectar errores básicos de sintaxis de inmediato.

Ejemplo de un error estructural común: Mapeo o sangría incorrecta.

# Sangría INCORRECTA para el puerto del contenedor
containers:
  - name: my-app
    image: myregistry/myapp:v1
    ports:
    - containerPort: 8080  # Debe ir sangrado debajo del elemento de la lista '-'

2. Errores de referencia y extracción de imágenes

Si los Pods entran en ImagePullBackOff o ErrImagePull, el problema está relacionado con el acceso a la imagen del contenedor.

• Error tipográfico en el nombre/etiqueta de la imagen (Tag): Vuelva a comprobar la ortografía del repositorio, el nombre y la etiqueta de la imagen.
• Autenticación de registro privado: Si está extrayendo desde un registro privado (como repositorios privados de Docker Hub o ECR/GCR), asegúrese de haber configurado correctamente un ImagePullSecret en la especificación del Pod y de haberlo referenciado.

# Fragmento que muestra el uso de ImagePullSecret
spec:
  imagePullSecrets:
  - name: my-registry-secret
  containers:
  # ... resto de la especificación del contenedor

3. Violaciones de solicitudes y límites de recursos

Si un Pod permanece en estado Pending (Pendiente) y los eventos mencionan recursos insuficientes, los nodos del clúster no pueden satisfacer los requisitos de CPU o memoria definidos en el YAML.

Verifique los límites especificados en su manifiesto de despliegue:

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1"

Pasos para la solución de problemas:
1. Utilice kubectl describe nodes para ver la capacidad disponible.
2. Si ve eventos como 0/3 nodes are available: 3 Insufficient cpu (0/3 nodos están disponibles: 3 CPU insuficientes), debe reducir las requests (solicitudes) en su YAML o agregar más nodos al clúster.

Problemas de configuración avanzados

Más allá de la sintaxis básica y la extracción de imágenes, las configuraciones complejas que involucran redes, almacenamiento y planificación (scheduling) pueden conducir a fallos difíciles de diagnosticar.

1. Probes (Sondas) mal configuradas (Liveness y Readiness)

Si un Pod pasa a CrashLoopBackOff, a menudo significa que el contenedor se inicia pero inmediatamente falla una comprobación, o se inicia pero falla repetidamente su sonda de preparación (readiness probe).

• Liveness Probes (Sondas de actividad): Si esto falla, Kubernetes reinicia el contenedor. Verifique los registros de la aplicación (kubectl logs <nombre-del-pod>) para ver por qué está fallando.
• Readiness Probes (Sondas de preparación): Si esto falla, el Pod se mantiene fuera de los endpoints del Service. Asegúrese de que la ruta, el puerto y el código de respuesta esperado coincidan con lo que realmente está sirviendo su aplicación.

Ejemplo de un error común de Readiness Probe: Apuntar al puerto equivocado o esperar HTTP cuando la aplicación solo expone TCP.

2. Fallos de volumen y PersistentVolumeClaim (PVC)

Si los Pods están pendientes debido a problemas de volumen, inspeccione el estado del PVC:

kubectl get pvc <nombre-del-pvc>

Si el estado del PVC es Pending, significa que el clúster no pudo encontrar una StorageClass coincidente o un PersistentVolume adecuado al que vincularse. Verifique los eventos del PVC para detectar errores de vinculación específicos.

3. Reglas de afinidad y antiafinidad

Las reglas de planificación complejas, como nodeAffinity o podAntiAffinity, pueden evitar que un Pod se planifique si ningún nodo satisface todos los criterios. Si los Pods permanecen en Pending y los eventos mencionan restricciones de planificación, revise estas reglas.

Por ejemplo, si requiere que un Pod se ejecute en un nodo con una etiqueta específica (nodeSelector) que ningún nodo existente posee, el Pod nunca se planificará.

# Ejemplo: Restricción del despliegue a nodos etiquetados como 'disktype: ssd'
spec:
  nodeSelector:
    disktype: ssd
  containers:
  # ...

Consejo de solución de problemas: Comente temporalmente las reglas restrictivas de nodeSelector o affinity. Si el Pod se planifica correctamente, sabrá que el problema reside en los criterios de selección.

Resumen del flujo de trabajo de depuración

Cuando se enfrente a un despliegue fallido, siga este camino estructurado:

1. Estado del despliegue: kubectl get deployments -> ¿Las réplicas informan estar listas?
2. Eventos del Pod: kubectl describe pod <pod-fallido> -> Verifique la sección Events (Eventos) para detectar errores inmediatos (ImagePull, OOMKilled, problemas de volumen).
3. Registros del contenedor: kubectl logs <pod-fallido> -> Si el contenedor arranca pero falla (CrashLoopBackOff), la lógica de la aplicación o las sondas de actividad (liveness probes) son sospechosas.
4. Verificación de recursos: Si el Pod está en Pending, verifique las restricciones de recursos (Insufficient cpu/memory) o los fallos de vinculación de volumen (estado del PVC).
5. Validación de configuración: Revise el YAML en busca de sangría, nombres de campos correctos y valores de recursos válidos (requests/limits).

Al verificar sistemáticamente el estado, los eventos y la configuración YAML subyacente frente a las expectativas de Kubernetes, puede aislar y resolver rápidamente la causa raíz de la mayoría de los fallos de despliegue.