Soluciona problemas relacionados con eventos de CrashLoopBackOff

En esta página, se explica cómo resolver problemas relacionados con eventos de CrashLoopBackOff en Pods en Google Kubernetes Engine (GKE).

Esta página está dirigida a los desarrolladores de aplicaciones que desean identificar problemas a nivel de la app, como errores de configuración o errores relacionados con el código, que provocan fallas en sus contenedores. También es para los administradores y operadores de la plataforma que necesitan identificar las causas raíz a nivel de la plataforma de los reinicios de contenedores, como el agotamiento de recursos, las interrupciones de nodos o los sondeos de funcionamiento mal configurados. Para obtener más información sobre los roles comunes y las tareas de ejemplo a las que hacemos referencia en el contenido de Trusted Cloud by S3NS , consulta Tareas y roles comunes de los usuarios de GKE.

Comprende un evento de CrashLoopBackOff

Cuando tu Pod se atasca en un estado CrashLoopBackOff, un contenedor dentro de él se inicia y falla o sale de forma repetida. Este CrashLoop hace que Kubernetes intente reiniciar el contenedor según su restartPolicy. Con cada reinicio que falla, el retraso de BackOff antes del siguiente intento aumenta de forma exponencial (por ejemplo, 10 s, 20 s, 40 s), hasta un máximo de cinco minutos.

Si bien este evento indica un problema en tu contenedor, también es un indicador de diagnóstico valioso. Un evento CrashLoopBackOff confirma que ya se completaron muchos pasos fundamentales de la creación del Pod, como la asignación a un nodo y la extracción de la imagen del contenedor. Este conocimiento te permite enfocar tu investigación en la app o la configuración del contenedor, en lugar de la infraestructura del clúster.

El estado CrashLoopBackOff se produce debido a la forma en que Kubernetes, específicamente el kubelet, controla la finalización del contenedor según la política de reinicio del Pod. Por lo general, el ciclo sigue este patrón:

1. Se inicia el contenedor.
2. El contenedor sale.
3. Kubelet observa el contenedor detenido y lo reinicia según el restartPolicy del Pod.
4. Este ciclo se repite, y el contenedor se reinicia después de un retraso de retirada exponencial cada vez mayor.

El restartPolicy del Pod es la clave de este comportamiento. La política predeterminada, Always, es la causa más común de este bucle, ya que reinicia un contenedor si sale por cualquier motivo, incluso después de una salida exitosa. Es menos probable que la política OnFailure cause un bucle, ya que solo se reinicia con códigos de salida distintos de cero, y la política Never evita el reinicio por completo.

Identifica los síntomas de un evento CrashLoopBackOff

Un Pod con el estado CrashLoopBackOff es el principal indicador de un evento CrashLoopBackOff.

Sin embargo, es posible que experimentes algunos síntomas menos obvios de un evento de CrashLoopBackOff:

• No hay réplicas en buen estado para una carga de trabajo.
• Una disminución considerable en las réplicas en buen estado
• Las cargas de trabajo con el ajuste de escala automático horizontal de Pods habilitado se escalan lentamente o no se escalan.

Si una carga de trabajo de system (por ejemplo, un agente de registros o de métricas) tiene el estado CrashLoopBackOff, es posible que también observes los siguientes síntomas:

• No se registran algunas métricas de GKE.
• Algunos gráficos y paneles de GKE tienen brechas.
• Problemas de conectividad en la red a nivel del Pod

Si observas alguno de estos síntomas menos evidentes, el siguiente paso será confirmar si se produjo un evento CrashLoopBackOff.

Confirma un evento de CrashLoopBackOff

Para confirmar e investigar un evento CrashLoopBackOff, recopila evidencia de los eventos de Kubernetes y los registros de la app del contenedor. Estas dos fuentes proporcionan diferentes perspectivas del problema, pero complementarias:

• Los eventos de Kubernetes confirman que un Pod falla.
• Los registros de la app del contenedor pueden mostrarte por qué falla el proceso dentro del contenedor.

Para ver esta información, selecciona una de las siguientes opciones:

Usa la guía interactiva de Pods con fallas

Después de confirmar un evento CrashLoopBackOff, comienza a solucionar el problema con la guía interactiva:

1. En la consola de Trusted Cloud , ve a la página Guía interactiva de GKE: Pods en un bucle de fallas.

   Ir a Pods en bucle de fallas

2. En la lista Clúster, selecciona el clúster para el que deseas solucionar el problema. Si no encuentras tu clúster, ingresa su nombre en el campo Filtro.

3. En la lista Espacio de nombres, selecciona el espacio de nombres para el que deseas solucionar el problema. Si no encuentras tu espacio de nombres, ingresa el espacio de nombres en el campo Filtro.

4. Revisa cada sección para ayudarte a responder las siguientes preguntas:

   1. Identify App Errors: ¿Qué contenedores se están reiniciando?
   2. Investiga los problemas de memoria insuficiente: ¿Hay una configuración incorrecta o algún error relacionado con la app?
   3. Investiga las interrupciones del nodo: ¿Las interrupciones en los recursos del nodo hacen que el contenedor se reinicie?
   4. Investiga las fallas de los sondeos en funcionamiento: ¿los sondeos en funcionamiento detienen tus contenedores?
   5. Correlaciona los eventos de cambio: ¿Qué sucedió cuando los contenedores comenzaron a fallar?

5. Opcional: Para recibir notificaciones sobre eventos CrashLoopBackOff futuros, en la sección Sugerencias para mitigaciones futuras, selecciona Crear una alerta.

Si el problema persiste después de usar el manual, lee el resto de la guía para obtener más información sobre cómo resolver los eventos CrashLoopBackOff.

Cómo resolver un evento de CrashLoopBackOff

En las siguientes secciones, se explica cómo resolver las causas más comunes de los eventos CrashLoopBackOff:

• Agotamiento de recursos (OOMKilled)
• Falla en el sondeo de funcionamiento
• App con configuración incorrecta

Cómo resolver el agotamiento de recursos

Un evento CrashLoopBackOff suele deberse a un problema de memoria insuficiente (OOM). Puedes confirmar si esta es la causa si el resultado de kubectl describe muestra lo siguiente:

Last State: Terminated
  Reason: OOMKilled

Para obtener información sobre cómo diagnosticar y resolver eventos de OOM, consulta Soluciona problemas de eventos de OOM.

Cómo resolver fallas en los sondeos de funcionamiento

Un sondeo de actividad es una verificación de estado periódica que realiza kubelet. Si el sondeo falla una cantidad específica de veces (la cantidad predeterminada es tres), kubelet reinicia el contenedor, lo que podría provocar un evento CrashLoopBackOff si las fallas del sondeo continúan.

Confirma si la causa es un sondeo de funcionamiento

Para confirmar si las fallas en la sonda de actividad están activando el evento CrashLoopBackOff, consulta tus registros de kubelet. Estos registros suelen contener mensajes explícitos que indican fallas en las sondas y los reinicios posteriores.

1. En la Trusted Cloud consola, ve a la página Explorador de registros.

   Ir al Explorador de registros

2. En el panel de consultas, filtra los reinicios relacionados con la prueba de funcionamiento ingresando la siguiente consulta:

   resource.type="k8s_node"
   log_id("kubelet")
   jsonPayload.MESSAGE:"failed liveness probe, will be restarted"
   resource.labels.cluster_name="CLUSTER_NAME"
   

   Reemplaza CLUSTER_NAME por el nombre del clúster.

3. Revise el resultado. Si una falla en el sondeo de funcionamiento es la causa de tus eventos CrashLoopBackOff, la consulta devolverá mensajes de registro similares a los siguientes:

   Container probe failed liveness probe, will be restarted
   

Después de confirmar que las sondas de actividad son la causa del evento CrashLoopBackOff, continúa con la solución de problemas de las causas comunes:

• Revisa la configuración del sondeo de funcionamiento.
• Inspecciona el uso de la CPU y la E/S del disco.
• Aborda las implementaciones grandes.
• Errores transitorios de dirección
• Aborda el consumo de recursos de la sonda de direcciones.

Revisa la configuración del sondeo de funcionamiento

Las sondas mal configuradas son una causa frecuente de eventos CrashLoopBackOff. Verifica los siguientes parámetros de configuración en el manifiesto de la sonda:

• Verifica el tipo de sondeo: La configuración del sondeo debe coincidir con la forma en que tu app informa su estado. Por ejemplo, si tu app tiene una URL de verificación de estado (como /healthz), usa el tipo de sondeo httpGet. Si su estado se determina ejecutando un comando, usa el tipo de sondeo exec. Por ejemplo, para verificar si un puerto de red está abierto y en modo de escucha, usa el tipo de sondeo tcpSocket.
• Verifica los parámetros de la sonda:
  • Ruta de acceso (para el tipo de sondeo httpGet): Asegúrate de que la ruta de acceso HTTP sea correcta y de que tu app realice verificaciones de estado en ella.
  • Puerto: Verifica que la app use y exponga el puerto configurado en la sonda.
  • Comando (para el tipo de sondeo exec): Asegúrate de que el comando exista dentro del contenedor, devuelva un código de salida de 0 para indicar éxito y se complete dentro del período timeoutSeconds configurado.
  • Tiempo de espera: Asegúrate de que el valor de timeoutSeconds sea suficiente para que la app responda, en especial durante el inicio o bajo carga.
  • Retraso inicial (initialDelaySeconds): Verifica si el retraso inicial es suficiente para que la app se inicie antes de que comiencen los sondeos.

Para obtener más información, consulta Configura sondeos de funcionamiento, inicio y preparación en la documentación de Kubernetes.

Inspecciona el uso de la CPU y las operaciones de E/S del disco

La contención de recursos genera tiempos de espera de sondeo, lo que es una causa importante de fallas en los sondeos de actividad. Para saber si el uso de recursos es la causa de la falla de la sonda de actividad, prueba las siguientes soluciones:

• Analiza el uso de CPU: Supervisa el uso de CPU del contenedor afectado y el nodo en el que se ejecuta durante los intervalos de sondeo. Una métrica clave para hacer un seguimiento es kubernetes.io/container/cpu/core_usage_time. El uso elevado de CPU en el contenedor o el nodo puede impedir que la app responda a la sonda a tiempo.
• Supervisa la E/S de disco: Verifica las métricas de E/S de disco del nodo. Puedes usar la métrica compute.googleapis.com/guest/disk/operation_time para evaluar la cantidad de tiempo dedicado a las operaciones de disco, que se clasifican por lecturas y escrituras. Una E/S de disco alta puede ralentizar significativamente el inicio del contenedor, la inicialización de la app o el rendimiento general de la app, lo que provoca tiempos de espera de sondeo.

Aborda las implementaciones grandes

En situaciones en las que se implementa una gran cantidad de Pods de forma simultánea (por ejemplo, con una herramienta de CI/CD como ArgoCD), un aumento repentino de Pods nuevos puede sobrecargar los recursos del clúster, lo que provoca el agotamiento de los recursos del plano de control. Esta falta de recursos retrasa el inicio de la app y puede provocar que los sondeos de funcionamiento fallen repetidamente antes de que las apps estén listas.

Para resolver este problema, prueba con las siguientes soluciones:

• Implementa implementaciones escalonadas: Implementa estrategias para implementar Pods en lotes o durante un período más largo para evitar sobrecargar los recursos del nodo.
• Reconfigura o ajusta la escala de los nodos: Si las implementaciones escalonadas no son factibles, considera actualizar los nodos con discos más rápidos o más grandes, o bien con Persistent Volume Claims, para controlar mejor el aumento de la demanda de E/S. Asegúrate de que el ajuste de escala automático del clúster esté configurado de forma adecuada.
• Espera y observa: En algunos casos, si el clúster no tiene una escasez grave de recursos, es posible que las cargas de trabajo se implementen después de una demora significativa (a veces, de 30 minutos o más).

Cómo solucionar errores transitorios

Es posible que la app experimente errores temporales o ralentizaciones durante el inicio o la inicialización que provoquen que la sonda falle inicialmente. Si la app se recupera, considera aumentar los valores definidos en los campos initialDelaySeconds o failureThreshold del manifiesto de la prueba de actividad.

Cómo abordar el consumo de recursos de la sonda

En casos excepcionales, la ejecución del sondeo de actividad puede consumir recursos significativos, lo que podría activar restricciones de recursos que podrían provocar que se cierre el contenedor debido a un cierre por falta de memoria (OOM). Asegúrate de que los comandos de sondeo sean ligeros. Es más probable que una sonda liviana se ejecute de forma rápida y confiable, lo que le otorga mayor fidelidad para informar con precisión el estado real de tu app.

Cómo resolver problemas de configuración incorrecta de la app

Las configuraciones incorrectas de la app provocan muchos eventos CrashLoopBackOff. Para comprender por qué se detiene tu app, el primer paso es examinar su código de salida. Este código determina la ruta de solución de problemas:

• El código de salida 0 indica una salida exitosa, lo que es inesperado para un servicio de ejecución prolongada y apunta a problemas con el punto de entrada del contenedor o el diseño de la app.
• Un código de salida distinto de cero indica una falla de la app, lo que dirige tu atención hacia errores de configuración, problemas de dependencia o errores en el código.

Cómo encontrar el código de salida

Para encontrar el código de salida de tu app, haz lo siguiente:

1. Describe el Pod:

   kubectl describe pod POD_NAME -n NAMESPACE_NAME
   

   Reemplaza lo siguiente:

   • POD_NAME: Es el nombre del Pod problemático.
   • NAMESPACE_NAME: Es el espacio de nombres del Pod.

2. En el resultado, revisa el campo Exit Code ubicado en la sección Last State del contenedor pertinente. Si el código de salida es 0, consulta Soluciona problemas de salidas exitosas (código de salida 0). Si el código de salida es un número distinto de 0, consulta Soluciona problemas relacionados con fallas de la app (código de salida distinto de cero).

Soluciona problemas relacionados con las salidas exitosas (código de salida 0)

Por lo general, un código de salida de 0 significa que el proceso del contenedor finalizó correctamente. Si bien este es el resultado que deseas para un trabajo basado en tareas, puede indicar un problema para un controlador de ejecución prolongada, como un Deployment, un StatefulSet o un ReplicaSet.

Estos controladores funcionan para garantizar que un Pod siempre se esté ejecutando, por lo que tratan cualquier salida como un error que se debe corregir. kubelet aplica este comportamiento cumpliendo con el restartPolicy del Pod (que, de forma predeterminada, es Always) y reiniciando el contenedor incluso después de una salida exitosa. Esta acción crea un bucle que, en última instancia, activa el estado CrashLoopBackOff.

Los motivos más comunes por los que se sale de la app de forma inesperada y correcta son los siguientes:

• El comando del contenedor no inicia un proceso persistente: Un contenedor permanece en ejecución solo mientras lo hace su proceso inicial (command o entrypoint). Si este proceso no es un servicio de ejecución prolongada, el contenedor se cierra en cuanto se completa el comando. Por ejemplo, un comando como ["/bin/bash"] sale de inmediato porque no tiene ningún script para ejecutar. Para resolver este problema, asegúrate de que el proceso inicial del contenedor inicie un proceso que se ejecute de forma continua.

• La app de trabajador se cierra cuando una cola de trabajo está vacía: Muchas apps de trabajador están diseñadas para verificar si hay una tarea en una cola y salir de forma limpia si la cola está vacía. Para resolver este problema, puedes usar un controlador de Job (que está diseñado para tareas que se ejecutan hasta completarse) o modificar la lógica de la app para que se ejecute como un servicio persistente.

• La app se cierra debido a una configuración faltante o no válida: Es posible que tu app se cierre de inmediato si le faltan instrucciones de inicio obligatorias, como argumentos de línea de comandos, variables de entorno o un archivo de configuración crítico.

  Para resolver este problema, primero inspecciona los registros de tu app en busca de mensajes de error específicos relacionados con la carga de la configuración o la falta de parámetros. Luego, verifica lo siguiente:

  • Argumentos o entorno de la app: Asegúrate de que todos los argumentos de línea de comandos y las variables de entorno necesarios se pasen correctamente al contenedor según lo previsto por tu app.
  • Presencia del archivo de configuración: Confirma que todos los archivos de configuración necesarios estén presentes en las rutas esperadas dentro del contenedor.
  • Contenido del archivo de configuración: Valida el contenido y el formato de tus archivos de configuración para detectar errores de sintaxis, campos obligatorios faltantes o valores incorrectos.

  Un ejemplo común de este problema es cuando una app está configurada para leer desde un archivo activado con un volumen ConfigMap. Si el objeto ConfigMap no está adjunto, está vacío o tiene claves con nombres incorrectos, es posible que una app diseñada para salir cuando falta su configuración se detenga con un código de salida de 0. En esos casos, verifica los siguientes parámetros de configuración: - El nombre ConfigMap en la definición del volumen de tu Pod coincide con su nombre real. - Las claves dentro de ConfigMap coinciden con lo que tu app espera encontrar como nombres de archivo en el volumen montado.

Cómo solucionar problemas de fallas de la app (código de salida distinto de cero)

Cuando un contenedor se cierra con un código distinto de cero, Kubernetes lo reinicia. Si el problema subyacente que causó el error persiste, la app volverá a fallar y el ciclo se repetirá hasta alcanzar el estado CrashLoopBackOff.

El código de salida distinto de cero es un indicador claro de que se produjo un error dentro de la app, lo que dirige tus esfuerzos de depuración hacia su funcionamiento interno y su entorno. Los siguientes problemas suelen causar esta finalización:

• Errores de configuración: Un código de salida distinto de cero suele indicar problemas con la configuración de la app o el entorno en el que se ejecuta. Verifica si tu app presenta los siguientes problemas habituales:

  • Falta el archivo de configuración: Es posible que la app no pueda ubicar o acceder a un archivo de configuración obligatorio.
  • Configuración no válida: El archivo de configuración puede contener errores de sintaxis, valores incorrectos o parámetros de configuración incompatibles, lo que provoca que la app falle.
  • Problemas de permisos: Es posible que la app no tenga los permisos necesarios para leer o escribir el archivo de configuración.
  • Variables de entorno: Las variables de entorno incorrectas o faltantes pueden provocar que la app no funcione correctamente o no se inicie.
  • entrypoint o command no válidos: Es posible que el comando especificado en el campo entrypoint o command del contenedor sea incorrecto. Este problema puede ocurrir con imágenes recién implementadas en las que la ruta al ejecutable es incorrecta o el archivo en sí no está presente en la imagen del contenedor. Esta configuración incorrecta suele generar el código de salida 128.

  • Actualizaciones de imágenes no controladas (etiqueta :latest): Si las imágenes de tu carga de trabajo usan la etiqueta :latest, es posible que los Pods nuevos extraigan una versión de imagen actualizada que introduzca cambios rotundos.

    Para garantizar la coherencia y la reproducibilidad, usa siempre etiquetas de imágenes específicas e inmutables (por ejemplo, v1.2.3) o resúmenes SHA (por ejemplo, sha256:45b23dee08...) en los entornos de producción. Esta práctica ayuda a garantizar que se extraiga el mismo contenido de imagen cada vez.

• Problemas de dependencia: Es posible que tu app falle si no puede conectarse a los otros servicios de los que depende, si no se puede autenticar o si no tiene permisos suficientes para acceder a ellos.

  • Servicio externo no disponible: Es posible que la app dependa de servicios externos (por ejemplo, bases de datos o APIs) a los que no se puede acceder debido a problemas de conectividad de red o interrupciones del servicio. Para solucionar este problema, conéctate al Pod. Para obtener más información, consulta Cómo depurar Pods en ejecución en la documentación de Kubernetes.

    Después de conectarte al Pod, puedes ejecutar comandos para verificar el acceso a archivos y bases de datos, o para probar la red. Por ejemplo, puedes usar una herramienta como curl para intentar acceder a la URL de un servicio. Esta acción te ayuda a determinar si un problema se debe a las políticas de red, al DNS o al servicio en sí.

  • Errores de autenticación: Es posible que la app no pueda autenticarse con servicios externos debido a credenciales incorrectas. Inspecciona los registros del contenedor para ver si hay mensajes como 401 Unauthorized (credenciales incorrectas) o 403 Forbidden (permisos insuficientes), que suelen indicar que la cuenta de servicio del Pod no tiene los roles de IAM necesarios para realizar llamadas a servicios externos Trusted Cloud by S3NS.

    Si usas la federación de Workload Identity de GKE, verifica que el identificador principal tenga los permisos necesarios para la tarea. Para obtener más información sobre cómo otorgar roles de IAM a principales con Workload Identity Federation for GKE, consulta Configura la autorización y los principales. También debes verificar que el uso de recursos del servidor de metadatos de GKE no haya superado sus límites.

  • Tiempos de espera agotados: Es posible que la app experimente tiempos de espera agotados cuando espere respuestas de servicios externos, lo que provoca fallas.

• Errores específicos de la app: Si la configuración y las dependencias externas parecen correctas, es posible que el error se encuentre en el código de la app. Inspecciona los registros de la app en busca de estos errores internos comunes:

  • Excepciones no controladas: Los registros de la app pueden contener seguimientos de pila o mensajes de error que indiquen excepciones no controladas o errores relacionados con el código.
  • Interbloqueos o bloqueos activos: Es posible que la app esté atascada en un interbloqueo, en el que varios procesos esperan que se completen entre sí. En este caso, es posible que la app no se cierre, pero deje de responder de forma indefinida.
  • Conflictos de puertos: Es posible que la app no se inicie si intenta vincularse a un puerto que ya está en uso por otro proceso.
  • Bibliotecas incompatibles: Es posible que la app dependa de bibliotecas o dependencias que faltan o que son incompatibles con el entorno de ejecución.

  Para encontrar la causa raíz, inspecciona los registros del contenedor en busca de un mensaje de error o un seguimiento de pila específicos. Esta información te ayuda a decidir si debes corregir el código de la app, ajustar los límites de recursos o corregir la configuración del entorno. Para obtener más información sobre los registros, consulta Acerca de los registros de GKE.

¿Qué sigue?

• Si no encuentras una solución a tu problema en la documentación, consulta Obtener asistencia para obtener más ayuda, incluidos consejos sobre los siguientes temas:

  • Abrir un caso de asistencia comunicándose con Atención al cliente de Cloud
  • Obtén asistencia de la comunidad haciendo preguntas en StackOverflow y usando la etiqueta google-kubernetes-engine para buscar problemas similares. También puedes unirte al canal de Slack #kubernetes-engine para obtener más asistencia de la comunidad.
  • Abrir errores o solicitudes de funciones con la herramienta pública de seguimiento de errores