Étiquettes, annotations et tolérances Kubernetes : guide pratique de dépannage

Introduction

Les étiquettes, annotations et teintes (taints) de Kubernetes sont des mécanismes essentiels pour organiser, décorer et contrôler le placement des charges de travail. Lorsqu'elles sont mal configurées, elles provoquent des défaillances subtiles : un pod qui ne se planifie jamais, un service qui ne sélectionne aucun point de terminaison, ou un outil qui ne trouve pas une métadonnée critique. Ce guide vous fournit des approches de dépannage pratiques, étape par étape, avec des commandes réelles, des sorties attendues et des actions de récupération.

Nous nous adressons aux développeurs, consultants DevOps et équipes techniques de startups qui doivent diagnostiquer et corriger rapidement et en toute sécurité les problèmes liés aux étiquettes, annotations et teintes. Chaque section suit un schéma opérationnel : observer l'état actuel, comprendre l'ampleur des dégâts, apporter une modification minimale et vérifier le résultat. Nous protégeons les données sensibles en utilisant des espaces réservés dans les exemples et en mettant l'accent sur la réversibilité.

À la fin de ce guide, vous serez capable d'inspecter les étiquettes et annotations, de déboguer les problèmes de planification causés par les teintes, de corriger les incompatibilités de sélecteurs et d'établir un flux de travail de dépannage reproductible.

Inventaire de la version et de l'environnement

Avant de modifier quoi que ce soit, confirmez votre version de Kubernetes et les ressources API pertinentes. Les étiquettes, annotations et teintes sont des fonctionnalités stables, mais le comportement peut varier légèrement selon les versions (par exemple, le format de sortie de kubectl change). Exécutez :

kubectl version --short

Sortie attendue (exemple) :

Client Version: v1.27.3
Kustomize Version: v5.0.1
Server Version: v1.27.3

Si votre client et votre serveur diffèrent de plus d'une version mineure, mettez à niveau votre client pour éviter les problèmes de compatibilité.

Ensuite, répertoriez les ressources affectées. Supposons que vous dépanniez un déploiement nommé webapp dans l'espace de noms prod :

kubectl get deployment webapp -n prod -o wide

Regardez la colonne SELECTOR. Un déploiement utilise des étiquettes pour sélectionner les pods. Si le sélecteur ne correspond pas aux étiquettes du modèle de pod, le déploiement ne gérera pas les nouveaux pods. Exemple de sortie :

NAME     READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS   IMAGES        SELECTOR
webapp   1/3     3            1           2d    nginx        nginx:1.25    app=webapp

Inspectez maintenant les étiquettes des pods :

kubectl get pods -n prod --show-labels

La sortie attendue inclut les étiquettes de chaque pod. Si un pod n'a pas app=webapp, il ne sera pas compté par le déploiement ni sélectionné par un service utilisant le même sélecteur.

Capturez l'état actuel avant toute intervention. Utilisez kubectl describe pour voir les événements et les détails :

kubectl describe deployment webapp -n prod

Recherchez des événements tels que ScalingReplicaSet ou SuccessfulCreate. Si les pods ne sont pas créés, l'incompatibilité de sélecteur peut en être la cause.

Un test rapide de connectivité consiste à utiliser le transfert de port. Cela évite d'exposer un service à l'extérieur :

kubectl port-forward pod/webapp-<pod-id> 8080:80

Ensuite, exécutez curl http://localhost:8080. Si cela fonctionne, le pod lui-même est sain ; le problème se situe probablement au niveau du service ou de la couche d'entrée.

Gardez vos tests locaux limités : appliquez un manifeste à la fois et vérifiez. Par exemple, appliquez un pod de débogage temporaire avec les mêmes étiquettes que la cible pour tester la sélection du service :

apiVersion: v1
kind: Pod
metadata:
  name: debug-pod
  labels:
    app: webapp
spec:
  containers:
  - name: debug
    image: busybox
    command: ['sh', '-c', 'sleep 3600']

Après l'avoir créé, vérifiez si les points de terminaison du service incluent ce pod. Cela isole les problèmes d'étiquettes/sélecteurs des problèmes d'application.

Chemin de configuration sûr

Les étiquettes et annotations sont des métadonnées ; leur modification peut avoir des effets étendus. Suivez toujours un chemin sûr :

1. Lisez les étiquettes/annotations actuelles avec kubectl get et -o yaml ou -o json. Ne vous fiez pas à la mémoire.
2. Identifiez tous les objets qui référencent l'étiquette (déploiements, services, politiques réseau, etc.).
3. Apportez une modification à la fois en utilisant kubectl label ou kubectl annotate avec le drapeau --overwrite uniquement si nécessaire.
4. Vérifiez l'effet immédiatement avec une commande de lecture.
5. Préparez une commande de retour en arrière au cas où la modification serait erronée.

Exemple : Vous devez ajouter une étiquette tier=frontend à tous les pods d'un déploiement, mais le sélecteur du déploiement n'inclut pas cette étiquette. Étiqueter directement les pods ne persistera pas car le déploiement contrôle le modèle de pod. Vous devez plutôt mettre à jour le modèle de pod du déploiement.

Commencez par extraire le YAML actuel du déploiement :

kubectl get deployment webapp -n prod -o yaml > webapp-deployment.yaml

Modifiez le fichier pour ajouter l'étiquette sous spec.template.metadata.labels :

spec:
  template:
    metadata:
      labels:
        app: webapp
        tier: frontend

Appliquez la modification :

kubectl apply -f webapp-deployment.yaml

Vérifiez l'état du déploiement :

kubectl rollout status deployment/webapp -n prod

Sortie attendue : deployment "webapp" successfully rolled out.

Si le déploiement échoue, revenez en arrière avec :

kubectl rollout undo deployment/webapp -n prod

Pour les annotations, le processus est similaire. Les annotations sont souvent utilisées par les contrôleurs d'entrée, les outils de surveillance ou les systèmes CI/CD. Modifier une annotation peut déclencher un rechargement ou une mise à jour de configuration. Exemple : modifiez l'annotation d'entrée nginx pour la taille du corps du client :

kubectl annotate ingress webapp-ingress nginx.ingress.kubernetes.io/client-body-buffer-size=16k --overwrite

Vérifiez la configuration de l'entrée avec kubectl describe ingress webapp-ingress -n prod. L'annotation doit apparaître dans la sortie.

Rappelez-vous : ne collez jamais de secrets dans les étiquettes ou annotations. Si vous devez stocker des données sensibles, utilisez les Secrets Kubernetes et référencez-les, ou utilisez un outil de gestion des secrets dédié. Les étiquettes et annotations sont visibles par toute personne ayant accès à l'API.

Vérification et diagnostics

La vérification consiste à confirmer que les étiquettes et les sélecteurs sont alignés et que les teintes et tolérances permettent la planification.

Alignement des étiquettes et des sélecteurs

Pour qu'un service route le trafic vers les pods, le selector du service doit correspondre aux étiquettes des pods. Si vous suspectez une incompatibilité de sélecteur, exécutez :

kubectl get endpoints <service-name> -n <namespace>

Si la colonne ENDPOINTS est vide (ou <none>), le service ne sélectionne aucun pod. Exemple :

NAME         ENDPOINTS   AGE
webapp-svc   <none>      10m

Comparez le sélecteur du service et les étiquettes des pods :

kubectl get svc webapp-svc -n prod -o jsonpath='{.spec.selector}'
kubectl get pods -n prod --show-labels | grep webapp

Si le sélecteur est app=webapp et que les pods ont app=webapp,version=v1, le service les sélectionne toujours car le sélecteur ne spécifie que app. Mais si le sélecteur du service est app=webapp,version=v2 et que les pods ont version=v1, les points de terminaison seront vides.

Pour corriger, mettez à jour les étiquettes du modèle de pod (via le déploiement) ou ajustez le sélecteur du service.

Diagnostics des teintes et tolérances

Les teintes sur les nœuds restreignent quels pods peuvent être planifiés. Les teintes courantes incluent node.kubernetes.io/not-ready, node.kubernetes.io/disk-pressure et des teintes personnalisées comme dedicated=experimental:NoSchedule.

Vérifiez les teintes des nœuds :

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

Exemple de sortie :

NAME       TAINTS
node-1     <none>
node-2     [dedicated=experimental:NoSchedule]

Si un pod n'est pas planifiable, vérifiez ses événements :

kubectl describe pod <pod-name> -n <namespace>

Recherchez des événements comme :

Warning   FailedScheduling   pod/webapp-xyz   0/3 nodes are available: 1 node(s) had untolerated taint {dedicated: experimental}, 2 Insufficient cpu.

Le message indique que la teinte n'est pas tolérée et/ou que les ressources sont insuffisantes.

Pour permettre au pod de s'exécuter sur le nœud teinté, ajoutez une tolérance à la spécification du pod :

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

Appliquez et vérifiez que le pod se planifie.

Pour une vérification rapide, vous pouvez créer un pod de test avec la même tolérance pour confirmer.

Modes de défaillance et récupération

Modes de défaillance courants et comment récupérer :

1. Incompatibilité du sélecteur de service

Symptôme : Le service n'a pas de points de terminaison, le trafic échoue. Diagnostic : kubectl get endpoints n'affiche rien ; kubectl describe svc montre le sélecteur ; les étiquettes des pods diffèrent. Récupération : Mettez à jour le sélecteur du service pour correspondre aux étiquettes des pods ou vice versa. Par exemple :

kubectl patch svc webapp-svc -n prod -p '{"spec":{"selector":{"app":"webapp"}}}'

2. Sélecteur de déploiement immuable

Symptôme : Vous essayez de modifier le sélecteur du déploiement avec kubectl apply et obtenez une erreur. Diagnostic : Message d'erreur : spec.selector: Invalid value: ... field is immutable. Récupération : Supprimez et recréez le déploiement, ou créez un nouveau déploiement avec le sélecteur souhaité et migrez le trafic. Assurez-vous d'avoir une sauvegarde du YAML du déploiement et envisagez une stratégie bleu-vert.

3. Teinte non tolérée

Symptôme : Le pod reste bloqué en état Pending. Diagnostic : Les événements du pod montrent FailedScheduling en raison d'une teinte non tolérée. Récupération : Ajoutez une tolérance à la spécification du pod, ou retirez la teinte du nœud si approprié :

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

Le - final retire la teinte. Vérifiez avec kubectl describe node node-2 | grep Taints.

4. Étiquette supprimée accidentellement

Symptôme : Les tableaux de bord de surveillance ou les politiques réseau cessent de fonctionner pour un ensemble de pods. Diagnostic : kubectl get pods --show-labels montre l'étiquette manquante. Récupération : Réajoutez l'étiquette via le modèle de pod du déploiement, pas seulement sur les pods en cours d'exécution, pour la rendre persistante. Si vous avez besoin d'une correction temporaire rapide sur les pods en cours :

kubectl label pods -l app=webapp tier=frontend

Mais rappelez-vous : si les pods sont gérés par un déploiement, l'étiquette sera écrasée lors de la prochaine mise à jour. Corrigez donc le modèle du déploiement.

5. Annotation écrasée par le contrôleur

Symptôme : Vous définissez une annotation, mais elle disparaît après une réconciliation. Diagnostic : Vérifiez quel contrôleur gère la ressource. Par exemple, un contrôleur d'entrée peut écraser les annotations. Récupération : Définissez l'annotation dans le manifeste source (par exemple, dans le dépôt GitOps) ou utilisez un webhook de mutation pour l'imposer. Pour les corrections ponctuelles, utilisez kubectl annotate --overwrite mais sachez qu'elle peut être réinitialisée.

Documentez toujours les étapes de récupération dans votre runbook. Avant d'apporter des modifications, prenez un instantané :

kubectl get deployment webapp -n prod -o yaml > before-webapp.yaml

Après modification, comparez ou restaurez si nécessaire :

kubectl apply -f before-webapp.yaml

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour toute session de dépannage d'étiquettes, d'annotations ou de teintes :

• [ ] Confirmez la version de Kubernetes et la correspondance client/serveur.
• [ ] Identifiez la ou les ressources affectées et l'espace de noms.
• [ ] Capturez l'état actuel avec kubectl get <resource> -o yaml et enregistrez dans un fichier.
• [ ] Listez toutes les références à l'étiquette/annotation/teinte en question.
• [ ] Pour les problèmes de planification, vérifiez les teintes des nœuds et les tolérances des pods.
• [ ] Pour les problèmes de service, vérifiez les points de terminaison et l'alignement des sélecteurs.
• [ ] Apportez une modification minimale en utilisant kubectl label, kubectl annotate, kubectl taint ou une édition de manifeste.
• [ ] Si vous modifiez un déploiement, appliquez et attendez rollout status.
• [ ] Vérifiez l'effet avec des commandes de lecture (get, describe, endpoints).
• [ ] En cas d'échec, revenez en arrière avec kubectl rollout undo ou en réappliquant le YAML sauvegardé.
• [ ] Documentez l'incident, la cause racine et la correction dans la base de connaissances de votre équipe.
• [ ] Envisagez des mesures préventives : application de politiques (par exemple, OPA), normalisation des étiquettes et documentation des teintes.

Exemple d'un ensemble d'étiquettes normalisé :

labels:
  app.kubernetes.io/name: webapp
  app.kubernetes.io/instance: webapp-prod
  app.kubernetes.io/version: "1.2.3"
  app.kubernetes.io/component: frontend
  app.kubernetes.io/part-of: ecommerce
  app.kubernetes.io/managed-by: helm

L'application cohérente de ces étiquettes facilite le dépannage et l'intégration avec les outils de l'écosystème.

Conclusion

Les étiquettes, annotations et teintes de Kubernetes sont simples mais puissantes. Leur dépannage exige une approche systématique : observer, diagnostiquer, apporter une modification minimale, vérifier et documenter la récupération. Utilisez les commandes et les exemples de ce guide pour construire vos propres runbooks.

Prochaine étape : choisissez un scénario à faible risque de cet article (par exemple, une étiquette manquante), reproduisez-le dans un espace de noms de test et pratiquez la boucle observation-modification-vérification. Enregistrez l'état actuel, exécutez les vérifications documentées, comparez avec les sorties attendues et examinez les dépendances telles que les services et les déploiements.

Un flux de travail fiable rend les défaillances visibles, protège les valeurs sensibles, limite les modifications aux ressources prévues et prépare la récupération avant qu'un incident ne survienne.