Étiquettes, annotations et marques Kubernetes : erreurs fréquentes et correctifs avec exemples pratiques

Introduction

Les étiquettes (labels), les annotations et les marques (taints) de Kubernetes sont des mécanismes fondamentaux pour organiser, décrire et contrôler le placement des charges de travail. Mais des étiquettes mal configurées, des annotations manquantes ou des marques incorrectes peuvent entraîner l'échec des déploiements, la perte de trafic des services et l'impossibilité de planifier des nœuds. Cet article fournit un guide pratique pour diagnostiquer et corriger les erreurs les plus courantes liées à ces primitives Kubernetes.

Nous couvrirons des scénarios de défaillance réels, fournirons des commandes kubectl concrètes et des extraits YAML, et expliquerons comment vérifier chaque correctif. Que vous soyez développeur, consultant DevOps ou membre d'une équipe de startup technique, ce guide vous aidera à passer d'un état défaillant à une résolution vérifiée.

L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier le résultat et documenter la procédure de récupération si l'état attendu n'est pas atteint.

Inventaire de la version et de l'environnement

Avant de résoudre tout problème lié aux étiquettes, annotations ou marques, recueillez des informations précises sur votre environnement Kubernetes. Cela inclut la version de Kubernetes, les ressources d'API concernées et l'état actuel des objets affectés.

Vérifier la version de Kubernetes et le support de l'API

Les étiquettes, annotations et marques sont stables depuis Kubernetes 1.2, mais certaines fonctionnalités (comme les effets de marque ou les configurations d'ingress basées sur les annotations) peuvent dépendre de la version. Confirmez la version de votre cluster avec :

kubectl version --client
# Sortie : Client Version: v1.27.0

Dans ce guide, nous supposons Kubernetes 1.25 ou ultérieur. Si vous utilisez une version plus ancienne, certaines commandes peuvent différer.

Inspecter les étiquettes et annotations actuelles

Avant d'apporter des modifications, capturez les étiquettes et annotations existantes sur une ressource. Utilisez kubectl get avec --show-labels et -o yaml pour voir toutes les métadonnées :

kubectl get pods my-pod -o yaml

Recherchez les champs metadata.labels et metadata.annotations. Par exemple :

metadata:
  labels:
    app: frontend
    tier: web
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "8080"

Si une étiquette ou une annotation est manquante ou a une valeur inattendue, cela peut être la cause première de votre problème.

Vérifier les marques des nœuds

Les marques sont définies sur les nœuds et doivent être tolérées par les pods pour y être planifiés. Listez toutes les marques sur vos nœuds :

kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints
# Sortie :
# NAME       TAINTS
# node-1     [key1=value1:NoSchedule]
# node-2     <none>

Si un nœud a une marque comme node-role.kubernetes.io/master:NoSchedule, seuls les pods avec une tolérance correspondante y seront planifiés.

Commandes d'observation en lecture seule

Utilisez ces commandes pour observer sans rien modifier :

kubectl get pods -o wide : affiche l'état des pods et leur placement sur les nœuds.
kubectl describe pod <nom> : affiche les événements, y compris les échecs de planification et les messages liés aux marques.
kubectl logs <nom> --previous : affiche les journaux d'une instance précédente du conteneur (utile pour les boucles de crash).
kubectl rollout status deployment/<nom> : vérifie si le déploiement a réussi.

Gardez le test local minimal : appliquez un manifeste à la fois, inspectez les ressources générées et vérifiez avec kubectl port-forward ou un service local de type LoadBalancer avant de passer à un équilibreur de charge cloud ou à un contrôleur d'ingress.

Question rapide 1 sur 2

Quel est le comportement automatique de Kubernetes concernant le placement des Pods pour les ressources de charge de travail comme les Deployments ?

Selon le passage, Kubernetes répartit automatiquement les Pods des ressources de charge de travail (telles que Deployment ou StatefulSet) sur différents nœuds d'un cluster pour aider à réduire l'impact des défaillances.

Chemin de configuration sûr

Lors de la modification d'étiquettes, d'annotations ou de marques, suivez une approche de changement minimal. Séparez toujours l'observation de l'intervention, capturez l'état actuel et comprenez le rayon d'impact.

Modifier les étiquettes

Les étiquettes sont des paires clé-valeur utilisées pour l'identification et la sélection. Opérations courantes :

Ajouter ou mettre à jour une étiquette :

  kubectl label pod my-pod app=frontend --overwrite

Supprimer une étiquette :

  kubectl label pod my-pod app-

Lister les étiquettes de tous les pods dans un namespace :

  kubectl get pods --show-labels

Erreur courante : Essayer de mettre à jour une étiquette utilisée par le sélecteur d'un Service ou d'un Deployment. Si vous modifiez une étiquette attendue par le sélecteur d'un Service, le Service peut cesser de router le trafic vers le pod. Vérifiez toujours que tout changement d'étiquette ne casse pas les sélecteurs.

Exemple de correctif : Supposons qu'un Deployment sélectionne les pods avec app=frontend, mais que vous ayez par erreur étiqueté un pod app=web. Le pod ne recevra pas de trafic du Service. Corrigez l'étiquette :

kubectl label pod my-pod app=frontend --overwrite

Puis vérifiez avec :

kubectl get endpoints my-service -o yaml
# L'IP du pod doit apparaître dans la liste subsets.addresses.

Modifier les annotations

Les annotations sont utilisées pour des métadonnées non identifiantes, souvent consommées par des outils comme les contrôleurs d'ingress, les systèmes de surveillance ou les fournisseurs cloud. Les modifications d'annotations n'affectent pas les sélecteurs, mais peuvent altérer le comportement.

Ajouter ou mettre à jour une annotation :

  kubectl annotate pod my-pod example.com/owner="dev-team"

Supprimer une annotation :

  kubectl annotate pod my-pod example.com/owner-

Erreur courante : Un contrôleur d'ingress s'appuie sur des annotations comme nginx.ingress.kubernetes.io/rewrite-target ou kubernetes.io/ingress.class. Si ces annotations sont manquantes ou incorrectes, l'ingress peut ne pas router correctement.

Exemple de correctif : Pour un Ingress NGINX, assurez-vous que l'annotation de classe est correctement définie. Pour Kubernetes 1.18+, la méthode recommandée est d'utiliser le champ ingressClassName, mais beaucoup utilisent encore l'annotation :

metadata:
  annotations:
    kubernetes.io/ingress.class: "nginx"

Vérifiez l'ingress avec :

kubectl describe ingress my-ingress
# Recherchez les sections Address et Rules.

Modifier les marques et les tolérances

Les marques sur les nœuds et les tolérances sur les pods contrôlent la planification. Une erreur courante est d'ajouter une marque qui empêche involontairement la planification des pods, ou d'oublier d'ajouter une tolérance aux pods système critiques.

Ajouter une marque à un nœud :

  kubectl taint nodes node-1 dedicated=experimental:NoSchedule

Supprimer une marque :

  kubectl taint nodes node-1 dedicated=experimental:NoSchedule-

Notez le trait d'union final après l'effet.

Lister les marques d'un nœud :

  kubectl describe node node-1 | grep Taints

Erreur courante : Appliquer une marque NoExecute sans tolérance peut évincer les pods existants. Par exemple, ajouter node.kubernetes.io/not-ready:NoExecute (qui est automatiquement ajouté par le contrôleur de nœud) ne doit pas être géré manuellement.

Exemple de correctif : Si vous avez accidentellement ajouté une marque key=value:NoExecute à un nœud et que des pods sont évincés, supprimez-la immédiatement :

kubectl taint nodes node-1 key=value:NoExecute-

Pour un pod qui doit s'exécuter sur un nœud marqué, ajoutez une tolérance dans la spécification du pod :

tolerations:
- key: "dedicated"
  operator: "Equal"
  value: "experimental"
  effect: "NoSchedule"

Puis vérifiez que le pod est planifié :

kubectl get pods -o wide
# Le pod doit être en cours d'exécution sur le nœud marqué.

Effectuez toujours les modifications dans un environnement non productif d'abord, et conservez une sauvegarde de la configuration d'origine.

Vérification et diagnostic

Après avoir apporté une modification, vérifiez que l'effet escompté a été atteint et diagnostiquez les problèmes restants.

Vérifier les modifications d'étiquettes et d'annotations

Utilisez kubectl get avec des formats de sortie pour confirmer le changement :

kubectl get pod my-pod -L app,tier
# Affiche des colonnes supplémentaires pour les étiquettes spécifiées.

Pour les annotations, utilisez -o jsonpath :

kubectl get pod my-pod -o jsonpath='{.metadata.annotations}'
# Sortie : {"example.com/owner":"dev-team"}

Si la sortie ne correspond pas, revérifiez la syntaxe de la commande et le nom de la ressource.

Diagnostiquer les échecs de planification dus aux marques

Lorsqu'un pod est bloqué en état Pending, vérifiez les événements :

kubectl describe pod my-pod
# Recherchez des événements comme :
# Warning  FailedScheduling  5s (x2 over 10s)  default-scheduler  0/3 nodes are available: 1 node(s) had taint {dedicated=experimental:NoSchedule}, that the pod didn't tolerate, 2 Insufficient cpu.

Ce message indique clairement une tolérance manquante. Vous pouvez également vérifier directement les marques des nœuds.

Utiliser dry-run et diff

Avant d'appliquer un changement, utilisez --dry-run=client pour voir ce qui serait modifié, et kubectl diff pour comparer l'état actuel avec le changement proposé :

kubectl label pod my-pod app=backend --dry-run=client -o yaml
kubectl diff -f pod.yaml

kubectl diff nécessite que l'objet existe déjà ou vous pouvez utiliser kubectl apply --dry-run=server pour une validation côté serveur.

Vérifier les journaux et l'état des pods

Si un pod ne se comporte pas comme prévu après un changement d'étiquette/annotation (par exemple, le trafic ne lui parvient pas), inspectez les journaux :

kubectl logs my-pod --tail=50

Et vérifiez l'état du pod :

kubectl get pod my-pod -o wide
# Assurez-vous qu'il est en cours d'exécution et sur le nœud attendu.

Modes de défaillance et récupération

Comprendre les modes de défaillance courants vous aide à récupérer rapidement en cas de problème.

Mode de défaillance 1 : Inadéquation du sélecteur de Service

Symptôme : Un Service ne route pas le trafic vers les pods même s'ils sont en cours d'exécution.

Diagnostic : Comparez le sélecteur du Service avec les étiquettes des pods :

kubectl get service my-service -o yaml
kubectl get pods --show-labels

Si les clés/valeurs du sélecteur ne correspondent pas aux étiquettes des pods, les endpoints seront vides.

Récupération : Mettez à jour soit les étiquettes des pods, soit le sélecteur du Service (de préférence les étiquettes des pods si le sélecteur est déjà déployé) :

kubectl label pod my-pod app=frontend --overwrite

Puis vérifiez :

kubectl get endpoints my-service
# Devrait afficher les IP des pods.

Mode de défaillance 2 : Annotation d'Ingress manquante

Symptôme : La ressource Ingress existe mais l'URL configurée renvoie 404 ou le backend par défaut.

Diagnostic : Vérifiez les annotations et le statut de l'ingress :

kubectl describe ingress my-ingress

Recherchez l'absence de kubernetes.io/ingress.class ou d'autres annotations spécifiques au contrôleur.

Récupération : Ajoutez l'annotation requise avec kubectl annotate ou modifiez le YAML :

kubectl annotate ingress my-ingress nginx.ingress.kubernetes.io/rewrite-target=/

Attendez quelques secondes puis testez à nouveau l'URL.

Mode de défaillance 3 : Une marque empêche la planification d'un pod

Symptôme : Le pod reste en état Pending avec une erreur de planification mentionnant des marques.

Diagnostic : Comme indiqué précédemment, utilisez kubectl describe pod pour voir la raison de l'échec. Confirmez la marque du nœud :

kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

Options de récupération :

Ajoutez une tolérance à la spécification du pod et réappliquez.
Supprimez la marque du nœud si elle a été ajoutée par erreur :

   kubectl taint nodes node-1 dedicated=experimental:NoSchedule-

Modifiez l'effet de la marque pour un effet moins restrictif (par exemple, de NoExecute à NoSchedule) si approprié.

Après la récupération, vérifiez :

kubectl get pods -o wide
# Le pod doit être planifié et en cours d'exécution.

Mode de défaillance 4 : La suppression accidentelle d'une étiquette casse le Deployment

Symptôme : Après la suppression d'une étiquette, le Deployment crée de nouveaux pods de façon incontrôlée ou les anciens pods sont orphelins.

Diagnostic : Vérifiez si l'étiquette faisait partie du sélecteur du Deployment :

kubectl get deployment my-deployment -o yaml

Regardez spec.selector.matchLabels. Si l'étiquette supprimée y figurait, le Deployment ne peut plus gérer ses pods.

Récupération : Restaurez l'étiquette sur les pods existants et assurez-vous que le sélecteur du Deployment correspond :

kubectl label pod my-pod app=frontend

Ou, si le Deployment a été créé de manière impérative, le sélecteur est immuable ; vous devrez peut-être recréer le Deployment avec le sélecteur d'origine.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant et après avoir apporté des modifications aux étiquettes, annotations et marques pour garantir une opération sûre.

Identifier la ressource et l'état actuel

Exécutez kubectl get <type-de-ressource> <nom> -o yaml pour voir les métadonnées actuelles.
Enregistrez les étiquettes, annotations ou marques actuelles dans un fichier texte pour la restauration.

Comprendre le rayon d'impact

Pour les étiquettes : vérifiez si un Service, Deployment ou autre sélecteur dépend de l'étiquette que vous prévoyez de modifier.
Pour les annotations : déterminez quels contrôleurs ou outils consomment l'annotation.
Pour les marques : vérifiez quels pods s'exécutent actuellement sur le nœud et s'ils tolèrent les marques existantes.

Utiliser dry-run lorsque possible

kubectl label ... --dry-run=client
kubectl taint ... --dry-run=client
kubectl annotate ... --dry-run=client

Appliquer le changement à une seule ressource d'abord

Ne modifiez pas plusieurs ressources en lot.

Vérifier l'effet immédiat

Pour les étiquettes : kubectl get pods -L <clé>
Pour les annotations : kubectl get pod <nom> -o jsonpath='{.metadata.annotations}'
Pour les marques : kubectl describe node <nom> | grep Taints
Vérifiez la planification des pods ou les endpoints des services selon le cas.

Surveiller tout comportement inattendu

Observez l'état des pods : kubectl get pods -w
Consultez les journaux et événements si nécessaire.

Documenter le changement et le plan de restauration

Conservez une copie de la configuration d'origine et la commande utilisée pour la restauration.

Conclusion

Les étiquettes, annotations et marques de Kubernetes sont puissantes mais peuvent causer des problèmes subtils en cas de mauvaise configuration. En suivant une approche systématique — observer, modifier de manière minimale, vérifier et documenter la récupération — vous pouvez éviter les pièges courants et résoudre rapidement les problèmes lorsqu'ils surviennent.

Cet article a couvert l'inventaire des versions, les chemins de configuration sûrs, les techniques de vérification et des modes de défaillance spécifiques avec des commandes kubectl pratiques. Utilisez la liste de contrôle opérationnelle pour guider votre dépannage. N'oubliez pas : testez toujours dans un environnement non productif d'abord et conservez des sauvegardes de vos configurations.

Comme prochaine étape, choisissez un changement à faible risque de ce guide, appliquez-le à une ressource de test et vérifiez le résultat à l'aide des commandes fournies. Ensuite, envisagez de documenter les procédures opérationnelles standard de votre équipe pour la gestion des étiquettes, annotations et marques.