Les clusters Kubernetes peuvent rencontrer plusieurs problèmes lors de la tentative d'extraction de vos images de conteneur. Lorsqu'une erreur se produit, vos pods saisiront un ImagePullBackOff Etat. Voici comment déboguer ce message commun mais crypté afin que vous puissiez obtenir vos services en ligne.
Comment fonctionne l'extraction d'images
Kubernetes doit récupérer une image lorsque vous créez un nouveau déploiement ou mettez à jour un déploiement existant avec une référence de balise différente. La responsabilité de l'extraction des images incombe au processus Kubelet sur chaque nœud de travail. Chaque image référencée par le manifeste d'un pod doit être accessible à tous les nœuds du cluster afin que l'un d'entre eux puisse répondre à une demande de planification de conteneur.
Le téléchargement peut échouer si le chemin de l'image est incorrect, si vous n'êtes pas correctement authentifié ou si le réseau tombe en panne. Lorsque cela se produit, Kubernetes « se retire » et planifie une autre tentative de téléchargement. Le délai avant le tirage suivant augmente de façon exponentielle chaque fois qu'une tentative échoue, jusqu'à une limite de cinq minutes.
Si votre pod affiche le ImagePullBackOff état, Kubernetes a connu plusieurs échecs d'extraction d'image successifs et attend maintenant avant de réessayer. Le conteneur ne pourra pas démarrer tant que l'image ne sera pas disponible.
Vous pouvez laisser le pod dans cet état si vous savez que le problème est dû aux conditions du réseau ou à une autre erreur transitoire. Kubernetes finira par effectuer une nouvelle tentative et réussira à acquérir l'image. Si ce n'est pas le cas, voici comment commencer le débogage afin que vous puissiez mettre en place votre pod.
Vérifiez les bases
Tout d'abord, il vaut la peine de vérifier les bases mêmes. Votre manifeste de ressources fait-il référence à une image valide qui existe réellement ? Vérifiez le chemin du registre et la balise d'image pour les fautes de frappe simples.
Vous pouvez inspecter l'état interne de Kubernetes avec le describe pod commande dans Kubectl. Cela vous donne plus d'informations que get pod et le tableau de bord Kubernetes fournissent.
kubectl describe pod my-pod --namespace my-namespace
Les modifications apportées au cycle de vie du pod sont affichées sous l'en-tête "Événements". Le premier événement sera Scheduled; il doit être suivi d'un Pulling événement pour la première tentative d'extraction. Après cela, vous verrez un Failed ou BackOff événement si l'extraction n'a pas pu réussir. Celles-ci seront répétées plus tard dans la liste si Kubernetes est toujours dans un cycle de recul et de nouvelle tentative.
Lecture du Message associés à ces événements fournit souvent la cause première du problème. Un manifest for image:tag not found message signifie que l'image est valide mais que vous avez spécifié une balise non valide. Si vous voyez does not exist or no pull access , vérifiez que les chemins d'accès au registre et à l'image sont corrects. Lorsque vous êtes sûr qu'ils ont raison, le problème sera lié à une authentification incorrecte.
Gestion des connexions au registre
Vous devez être connecté avant d'extraire des images privées. Dans Kubernetes, il s'agit d'un mécanisme en deux étapes :créez un secret contenant les informations d'identification, puis référencez ce secret dans vos définitions de pod.
Le champ Pod s'appelle imagePullSecrets . Il doit indiquer un secret Kubernetes qui fournit un jeton de connexion pour le registre. Ce secret doit stocker une valeur JSON compatible Docker.
apiVersion: v1
kind: 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
Ce manifeste montre comment créer un secret qui vous connecte à registry.example.com en tant qu'demo-user avec le mot de passe my-password . Le Pod fait référence au secret par son nom. Les processus Kubelet sur les nœuds de votre cluster incluront le Docker config.json extrait lorsqu'ils extraient des images du registre.
L'extrait doit être encodé en Base64 pour être une valeur secrète Kubernetes valide. Vous pouvez utiliser une valeur pré-encodée ou diriger du texte brut via b64enc de YAML , comme indiqué dans le manifeste ci-dessus.
Le type d'informations d'identification que vous utilisez dépend de votre registre. Dans de nombreux cas, password sera en fait un jeton d'accès personnel ou une clé API. Docker Hub nécessite un jeton d'accès généré dans les paramètres de votre compte si l'authentification à deux facteurs est activée sur votre compte.
Limites de taux de registre
Si vous avez vérifié l'URL de votre registre, le nom de la balise d'image et les identifiants de connexion, vous verrez peut-être ImagePullBackOff en raison des limites de débit du registre. Docker Hub vous limite désormais à 100 chargements de conteneurs toutes les six heures. Cela passe à 200 tirages toutes les six heures si vous fournissez vos identifiants de connexion. Ce plafond pourrait être atteint rapidement dans un cluster actif avec de nombreux pods fréquemment déployés.
Un échec d'extraction dû à une limite de débit se manifestera de la même manière qu'un problème d'authentification. Vous devrez attendre que suffisamment de temps se soit écoulé pour que le plafond expire. Kubernetes devrait alors réussir à extraire l'image, ce qui affichera vos pods.
Pour une atténuation à plus long terme, envisagez d'exécuter votre propre registre ou proxy dans le cluster pour mettre en cache vos images. Cela peut réduire considérablement la fréquence à laquelle vous accédez aux serveurs de Docker, vous aidant ainsi à rester dans les limites de débit.
Résumé
Les pods Kubernetes entrent un ImagePullBackOff indiquer lorsqu'un nœud ne parvient pas à extraire une image. Kubelet retentera périodiquement l'extraction afin que les erreurs transitoires ne nécessitent aucune intervention manuelle pour être résolues.
Lorsque vous êtes sûr qu'un ImagePullBackOff n'est pas juste un problème temporaire, commencez par vous assurer que le chemin d'accès à l'image du pod est valide. Si cela se vérifie, suspectez des identifiants de connexion incorrects ou une allocation de limitation de débit épuisée. Utiliser kubectl describe exposera la séquence d'événements qui ont conduit à l'échec.
Enfin, vous pouvez essayer d'extraire vous-même l'image d'une autre machine pour vous assurer que le serveur de registre distant est réellement opérationnel. Si vous pouvez extraire l'image mais que votre cluster ne le peut pas, vous pourriez avoir des problèmes de réseau plus généraux empêchant vos nœuds d'atteindre le registre.