Los clústeres de Kubernetes pueden encontrar varios problemas al intentar extraer las imágenes de su contenedor. Cuando ocurre un error, sus Pods entrarán en un estado ImagePullBackOff. Aquí se explica cómo depurar este mensaje común pero críptico para que pueda obtener sus servicios en línea.
Cómo funcionan las extracciones de imágenes
Kubernetes necesita recuperar una imagen cuando crea una nueva implementación o actualiza una existente con una referencia de etiqueta diferente. La responsabilidad de extraer imágenes recae en el proceso de Kubelet en cada nodo trabajador. Cada imagen a la que hace referencia el manifiesto de un Pod debe ser accesible para todos los nodos del clúster para que cualquiera de ellos pueda cumplir con una solicitud de programación de contenedores.
La descarga podría fallar si la ruta de la imagen es incorrecta, no está autenticado incorrectamente o la red se cae. Cuando esto sucede, Kubernetes “retrocede” y programa otro intento de descarga. El retraso antes del siguiente tirón aumenta exponencialmente cada vez que falla un intento, hasta un límite de cinco minutos.
Si su Pod muestra el estado ImagePullBackOff, Kubernetes ha tenido múltiples fallas sucesivas en la extracción de imágenes y ahora está esperando antes de volver a intentarlo. El contenedor no podrá iniciarse hasta que la imagen esté disponible.
Puede dejar el Pod en este estado si sabe que el problema se debe a condiciones de la red u otro error transitorio. Kubernetes finalmente completará otro reintento y adquirirá la imagen con éxito. Si ese no es el caso, aquí se explica cómo comenzar a depurar para que pueda activar su Pod.
Verifique los conceptos básicos
En primer lugar, vale la pena comprobar los conceptos básicos. ¿Su manifiesto de recursos hace referencia a una imagen válida que realmente existe? Verifique la ruta del registro y la etiqueta de la imagen para detectar errores tipográficos simples.
Puede inspeccionar el estado interno de Kubernetes con el
describe pod
comando en Kubectl. Esto le da más información que
get pod
y el panel de Kubernetes proporcionan.
kubectl describe pod my-pod --namespace my-namespace
Los cambios en el ciclo de vida del Pod se muestran bajo el encabezado “Eventos”. El primer evento será programado; debe ir seguido de un evento de extracción para el primer intento de extracción. Después de esto, verá un evento Failed o BackOff si la extracción no se pudo realizar correctamente. Estos se repetirán más adelante en la lista si Kubernetes todavía se encuentra en un ciclo de retroceso y reintento.
La lectura del Mensaje asociado con estos eventos a menudo proporciona la causa raíz del problema. Un manifiesto para el mensaje imagen: etiqueta no encontrada significa que la imagen es válida pero usted ha especificado una etiqueta no válida. Si ve que no existe o no tiene acceso de extracción, verifique que las rutas del registro y de las imágenes sean correctas. Cuando esté seguro de que tienen razón, el problema estará relacionado con una autenticación incorrecta.
Administrar inicios de sesión del registro
Debes iniciar sesión antes de extraer imágenes privadas. En Kubernetes, es un mecanismo de dos pasos: crear un secreto que contenga credenciales y luego hacer referencia a ese secreto en las definiciones de su Pod.
El campo Pod se llama imagePullSecrets. Debe indicar un secreto de Kubernetes que proporcione un token de inicio de sesión para el registro. Este secreto debería almacenar un valor JSON compatible con Docker.
apiVersion: v1kind: Secret
type: kubernetes.io/dockerconfigjson
metadata:
name: image-pull-secret
data:
.dockerconfigjson: {{ "{"auths": {"registry.example.com": {"username": "demo-user", "password": "my-password"}}}" | b64enc }}
apiVersion: v1
kind: Pod
metadata:
name: my-pod
spec:
containers:
- name: my-container
image: registry.example.com/my-image:latest
imagePullSecrets:
- name: image-pull-secret
Este manifiesto muestra cómo crear un secreto que lo registre en registro.ejemplo.com como usuario de demostración con la contraseña mi-contraseña. El Pod hace referencia al secreto por su nombre. Los procesos de Kubelet en los nodos de su clúster incluirán Docker configuración.json fragmento cuando extraen imágenes del registro.
El fragmento debe estar codificado en Base64 para que sea un valor secreto de Kubernetes válido. Puede utilizar un valor precodificado o canalizar texto sin formato a través de b64enc de YAML, como se muestra en el manifiesto anterior.
El tipo de credenciales que utilice dependerá de su registro. En muchos casos, la contraseña será en realidad un token de acceso personal o una clave API. Docker Hub requiere un token de acceso generado en la configuración de su cuenta si tiene habilitada la autenticación de dos factores en su cuenta.
Límites de tasa de registro
Si ha verificado la URL de su registro, el nombre de la etiqueta de imagen y las credenciales de inicio de sesión, es posible que vea ImagePullBackOff debido a los límites de velocidad del registro. Docker Hub ahora le restringe a 100 extracciones de contenedores cada seis horas. Esto aumenta a 200 extracciones cada seis horas si proporciona sus credenciales de inicio de sesión. Ese límite podría alcanzarse rápidamente en un clúster activo con muchos Pods implementados con frecuencia.
Un error de extracción debido a un límite de velocidad se manifestará de la misma manera que un problema de autenticación. Deberá esperar hasta que transcurra el tiempo suficiente para que expire el límite. Luego, Kubernetes debería extraer con éxito la imagen y hacer aparecer sus Pods.
Para una mitigación a más largo plazo, considere ejecutar su propio registro o proxy en el clúster para almacenar en caché sus imágenes. Esto puede reducir significativamente la frecuencia con la que accede a los servidores de Docker, lo que le ayudará a mantenerse dentro de los límites de velocidad.
Resumen
Los pods de Kubernetes entran en un estado ImagePullBackOff cuando un nodo no puede extraer una imagen. Kubelet reintentará periódicamente la extracción para que los errores transitorios no requieran ninguna intervención manual para solucionarlos.
Cuando esté seguro de que ImagePullBackOff no es solo un problema temporal, comience asegurándose de que la ruta de la imagen del Pod sea válida. Si eso es así, sospeche de credenciales de inicio de sesión incorrectas o de una asignación límite de velocidad agotada. El uso de kubectl describe expondrá la secuencia de eventos que llevaron al error.
Como última opción, puede intentar extraer la imagen usted mismo desde otra máquina para asegurarse de que el servidor de registro remoto esté realmente activo. Si puede extraer la imagen pero su clúster no, es posible que tenga problemas de red más generales que impidan que sus nodos lleguen al registro.