Name: Tremplin Numérique
Price range: $$$

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 entreront un ImagePullBackOff Etat. Voici comment déboguer ce message commun mais cryptique afin que vous puissiez obtenir vos services en ligne.

Sommaire

Comment fonctionnent les extractions 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 êtes mal authentifié ou si le réseau tombe en panne. Lorsque cela se produit, Kubernetes « retraite » et planifie une autre tentative de téléchargement. Le délai avant le prochain tirage augmente de façon exponentielle à chaque échec d’une tentative, jusqu’à une limite de cinq minutes.

Si votre Pod affiche le ImagePullBackOff état, Kubernetes a connu plusieurs échecs successifs d’extraction d’image 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 acquérir avec succès l’image. Si ce n’est pas le cas, voici comment démarrer le débogage afin de pouvoir ouvrir votre Pod.

Vérifiez les bases

Tout d’abord, il vaut la peine de vérifier les bases. Votre manifeste de ressource 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 changements dans le cycle de vie du Pod sont affichés sous l’en-tête « Events ». Le premier événement sera Scheduled; il doit être suivi d’un Pulling événement pour la première tentative de tirage. Après cela, vous verrez un Failed ou alors BackOff événement si la traction ne pouvait pas réussir. Ceux-ci seront répétés plus tard dans la liste si Kubernetes est toujours dans un cycle d’arrêt et de nouvelle tentative.

Lire le Message associé à ces événements fournit souvent la cause première du problème. UNE manifest for image:tag not found message signifie que l’image est valide mais que vous avez spécifié une balise non valide. Si tu vois does not exist or no pull access, vérifiez que le registre et les chemins d’accès aux images 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 des informations d’identification, puis référencez ce secret dans vos définitions de pod.

Le champ Pod est appelé 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 comme 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 codé en Base64 pour être une valeur secrète Kubernetes valide. Vous pouvez utiliser une valeur pré-encodée ou envoyer du texte brut via YAML b64enc, comme indiqué dans le manifeste ci-dessus.

Le type d’informations d’identification que vous utilisez dépendra 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 vous avez activé l’authentification à deux facteurs sur votre compte.

Limites de débit de registre

Si vous avez vérifié l’URL de votre registre, le nom de la balise d’image et les informations de connexion, vous verrez peut-être ImagePullBackOff en raison des limites de taux de registre. Docker Hub vous limite désormais à 100 extractions de conteneurs toutes les six heures. Cela passe à 200 pulls toutes les six heures si vous fournissez vos identifiants de connexion. Ce plafond peut ê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, amenant vos pods.

Pour une atténuation à plus long terme, envisagez d’exécuter votre propre registre ou proxy en 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 à rester dans les limites de débit.

Résumé

Les pods Kubernetes entrent dans un ImagePullBackOff état lorsqu’un nœud ne parvient pas à extraire une image. Kubelet réessaiera périodiquement l’extraction afin que les erreurs transitoires ne nécessitent aucune intervention manuelle pour être résolues.

Quand tu es sûr qu’un ImagePullBackOff n’est pas seulement un blip temporaire, commencez par vous assurer que le chemin de 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. En utilisant kubectl describe exposera la séquence des événements qui ont conduit à l’échec.

Comme dernière option, 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 actif. Si vous pouvez extraire l’image mais pas votre cluster, vous pourriez avoir des problèmes de réseau plus généraux empêchant vos nœuds d’atteindre le registre.