Depuración de Despliegues Fallidos: Identificación de Errores Comunes en YAML y Configuración

Los fallos en los despliegues de Kubernetes suelen manifestarse como pods atascados en estado Pending, ImagePullBackOff, CrashLoopBackOff o con cero réplicas disponibles. La causa suele ser visible en los eventos, pero es necesario inspeccionar el Deployment, ReplicaSet y Pods en el orden correcto.

Esta guía recorre las comprobaciones que suelen encontrar errores en YAML, problemas de extracción de imágenes, sondas defectuosas, restricciones de recursos y reglas de programación que impiden que tu despliegue se vuelva saludable.

Primeros Pasos: Verificación del Estado del Despliegue y Eventos

Cuando un despliegue falla, tus primeros pasos de diagnóstico deben incluir siempre la verificación del recurso principal y los eventos asociados a 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. Inspeccionar la Salud del Despliegue

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

kubectl get deployments <nombre-del-despliegue>

Si el estado del despliegue muestra pocas o ninguna réplica lista, procede a verificar el ReplicaSet.

2. Revisar Eventos del ReplicaSet y Pods

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

kubectl describe rs <nombre-del-replicaset>

Crucialmente, examina la sección Events al final de la salida. Esta sección detalla acciones recientes, incluyendo intentos de programación, fallos de extracción de imágenes y problemas de montaje de volúmenes. Estos eventos suelen ser la prueba concluyente.

Finalmente, verifica los Pods mismos, ya que reportan el fallo inmediato:

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

Busca los campos State y Reason en la descripción del pod. Las razones comunes incluyen ImagePullBackOff, ErrImagePull, CrashLoopBackOff y Pending.

Errores Comunes de Configuración en Manifiestos YAML

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

1. Errores de Sintaxis y Estructura en 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: Usa un Linter Siempre valida la sintaxis de tu YAML antes de aplicarlo. Herramientas como yamllint o el soporte integrado del IDE pueden detectar errores de sintaxis básicos de inmediato.

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

# INCORRECTO: containers pertenece a spec.template.spec, no directamente a spec.template
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    metadata:
      labels:
        app: my-app
    containers:
      - name: my-app
        image: myregistry/myapp:v1

Ubicación correcta:

spec:
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: myregistry/myapp:v1
          ports:
            - containerPort: 8080

2. Errores de Referencia y Extracción de Imágenes

Si los Pods entran en estado 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: Verifica la ortografía del repositorio, nombre y etiqueta de la imagen.
• Autenticación en registro privado: Si extraes de un registro privado, asegúrate de haber creado un secreto de extracción de imagen y referenciarlo como imagePullSecrets en la especificación del Pod.

# Fragmento que muestra el uso de ImagePullSecret
spec:
  imagePullSecrets:
    - name: my-registry-secret
  containers:
    - name: my-app
      image: private.example.com/my-app:v1

3. Violaciones de Solicitudes y Límites de Recursos

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

Verifica los límites especificados en tu manifiesto de despliegue:

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

Pasos de Solución de Problemas:

1. Usa kubectl describe nodes para ver la capacidad disponible.
2. Si ves eventos como 0/3 nodes are available: 3 Insufficient cpu, debes reducir las requests en tu YAML o agregar más nodos al clúster.

Problemas Avanzados de Configuración

Más allá de la sintaxis básica y la extracción de imágenes, configuraciones complejas que involucran redes, almacenamiento y programación pueden llevar a fallos difíciles de diagnosticar.

1. Sondas Mal Configuradas (Liveness y Readiness)

Si un Pod transiciona a CrashLoopBackOff, a menudo significa que el contenedor se inicia pero falla inmediatamente una verificación, o se inicia pero falla repetidamente su sonda de readiness.

• Sondas Liveness: Si esta falla repetidamente, Kubernetes reinicia el contenedor. Verifica kubectl describe pod <nombre-del-pod> para eventos de fallo de sonda y kubectl logs <nombre-del-pod> --previous después de un reinicio.
• Sondas Readiness: Si esta falla, el Pod sigue ejecutándose pero se mantiene fuera de los endpoints del Service. Asegúrate de que la ruta, el puerto y el código de respuesta esperado coincidan con lo que tu aplicación realmente sirve.

Ejemplo de un error común en la sonda Readiness: Apuntar al puerto incorrecto 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, inspecciona 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 un StorageClass coincidente o un PersistentVolume adecuado para vincular. Verifica los eventos del PVC para errores de vinculación específicos.

3. Reglas de Afinidad y Anti-Afinidad

Las reglas complejas de programación, como nodeAffinity o podAntiAffinity, pueden impedir involuntariamente que un Pod se programe si ningún nodo satisface todos los criterios. Si los Pods permanecen en Pending y los eventos mencionan restricciones de programación, revisa estas reglas.

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

# Ejemplo: Restringir el despliegue a nodos etiquetados con 'disktype: ssd'
spec:
  nodeSelector:
    disktype: ssd
  containers:
  # ...

Consejo de Solución de Problemas: Comenta temporalmente las reglas restrictivas de nodeSelector o affinity. Si el Pod se programa con éxito, sabes que el problema está en los criterios de selección.

Flujo de Trabajo de Depuración

Cuando te enfrentes a un despliegue fallido, sigue este camino estructurado:

1. Estado del Despliegue: kubectl get deployments -> ¿Las réplicas reportan estar listas?
2. Eventos del Pod: kubectl describe pod <pod-fallido> -> Verifica la sección Events para errores inmediatos (ImagePull, OOMKilled, problemas de volumen).
3. Registros del Contenedor: kubectl logs <pod-fallido> -> Si el contenedor se inicia pero se bloquea (CrashLoopBackOff), la lógica de la aplicación o las sondas liveness son sospechosas.
4. Verificación de Recursos: Si el Pod está en Pending, verifica restricciones de recursos (Insufficient cpu/memory) o vinculaciones de volumen fallidas (estado del PVC).
5. Validación de Configuración: Revisa el YAML en busca de sangría, nombres de campo correctos y valores de recursos válidos (requests/limits).

Trabaja a partir de la evidencia del clúster en lugar de adivinar. Verifica estado, eventos, registros, recursos y estructura del manifiesto en ese orden, luego realiza el cambio más pequeño en el YAML que coincida con el error que encontraste.