Étiquettes Kubernetes, annotations et teintures : liste de contrôle pour la production avec exemples pratiques

Introduction

Les étiquettes Kubernetes, les annotations et les teintures figurent parmi les primitives les plus puissantes, mais souvent mal comprises, pour exploiter des clusters en production. Les étiquettes sont des paires clé-valeur servant à organiser et sélectionner des ressources. Les annotations contiennent des métadonnées non identifiantes à destination des outils et des humains. Les teintures repoussent les pods d’un nœud à moins que ces pods ne portent des tolérances correspondantes. Ensemble, elles contrôlent l’ordonnancement, le routage des services, l’observabilité et les flux de travail opérationnels, mais une mauvaise configuration peut provoquer des échecs silencieux, une sur- ou sous-ordonnancement et un diagnostic difficile.

Cet article fournit une liste de contrôle des opérations de production pour les étiquettes, les annotations et les teintures, avec des exemples pratiques qui vous mènent de l’observation d’un problème à la vérification d’une correction. Il s’adresse aux ingénieurs de plateforme, aux consultants DevOps et aux équipes techniques de startups qui doivent gérer des clusters Kubernetes en toute sécurité. Nous mettons l’accent sur des commandes concrètes, les sorties attendues, les signaux d’échec et les décisions de récupération, pas sur la théorie abstraite.

Le principe directeur 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 manière de récupérer si l’état attendu n’est pas atteint. Nous aborderons l’inventaire des versions et de l’environnement, les chemins de configuration sûrs, la vérification et le diagnostic, les modes d’échec et la récupération, ainsi qu’une liste de contrôle consolidée des opérations. Nous incluons également des vérifications rapides interactives pour renforcer les concepts clés.

Inventaire des versions et de l’environnement

Avant de toucher aux étiquettes, annotations ou teintures, vous devez savoir exactement ce que vous exécutez et dans quel contexte. Cette section établit une référence et évite des changements fondés sur des hypothèses obsolètes.

Identifier la version et la distribution de Kubernetes

Exécutez la commande en lecture seule suivante :

kubectl version --short

La sortie attendue ressemble à :

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

La version du serveur vous indique les fonctionnalités d’API disponibles et les comportements des étiquettes/annotations. Par exemple, topology.kubernetes.io/zone est devenue stable dans la version 1.20, et les étiquettes pod-security.kubernetes.io/* sont appliquées à partir de la 1.23. Si vous gérez une distribution managée comme EKS, GKE ou AKS, notez la version exacte de la plateforme, car elle peut avoir des fonctionnalités rétroportées ou des restrictions.

Inventorier l’utilisation actuelle des étiquettes, annotations et teintures

Capturez l’état actuel avec horodatage avant tout changement. Utilisez une commande qui produit les données dans un format lisible par machine pour une comparaison ultérieure.

# Lister toutes les étiquettes et annotations de chaque pod dans l'espace de noms par défaut
kubectl get pods -n default -o json | jq '.items[] | {name: .metadata.name, labels: .metadata.labels, annotations: .metadata.annotations}' > pod-metadata-before.json

Stockez ce fichier avec un horodatage dans le nom, par exemple pod-metadata-before-20250314-1045.json. Cet instantané est votre référence de restauration.

Pour les teintures, inspectez les nœuds :

kubectl get nodes -o json | jq '.items[] | {name: .metadata.name, taints: .spec.taints}' > node-taints-before.json

Si votre cluster est grand, filtrez par espaces de noms ou pools de nœuds spécifiques pour garder les données gérables.

Vérifier les prérequis pour des changements sûrs

• Vous avez configuré kubectl pour le bon contexte de cluster. Confirmez avec kubectl config current-context.
• Vous disposez des autorisations de lecture et d’écriture sur les ressources que vous prévoyez de modifier. Sinon, demandez une élévation ou utilisez un compte de service avec une RBAC limitée.
• Vous disposez d’une sauvegarde ou d’une source de vérité basée sur Git pour tous les manifestes que vous modifierez.

Liste de contrôle pratique de l’inventaire

Exécutez les commandes suivantes et enregistrez les sorties :

kubectl get pods -o wide

Cela affiche le placement des pods, les noms des nœuds et leur état. Notez tout pod bloqué en Pending en raison de teintures.

kubectl describe pod <nom-du-pod>

Cherchez sous Events les échecs d’ordonnancement liés aux teintures, par exemple 0/3 nodes are available: 1 node(s) had untolerated taint {key: value}.

kubectl get nodes --show-labels

Cela liste toutes les étiquettes des nœuds, y compris les standards comme kubernetes.io/hostname et les personnalisées que vous avez appliquées.

Garder le test local restreint

Avant d’apporter des modifications en production, testez dans un environnement local ou de préproduction qui reflète la version de production et la disposition des nœuds. Si possible, utilisez un outil comme kind ou minikube avec une configuration multi-nœuds pour simuler le comportement des teintures. Vérifiez que vos commandes fonctionnent et produisent les résultats attendus avant de toucher à la production.

Vérification rapide 1 : Quelle annotation enregistre une liste séparée par des virgules des étiquettes de fonctionnalités de nœud gérées par Node Feature Discovery ?

• [ ] nfd.node.kubernetes.io/feature-labels
• [ ] kubernetes.io/hostname
• [ ] authorization.k8s.io/decision
• [ ] pod-security.kubernetes.io/audit-violations

<details> <summary>Révéler la réponse</summary>

L’annotation nfd.node.kubernetes.io/feature-labels enregistre une liste séparée par des virgules des étiquettes de fonctionnalités de nœud gérées par Node Feature Discovery (NFD). </details>

Chemin de configuration sûr

Avec votre référence en main, vous pouvez maintenant effectuer des changements maîtrisés. Cette section montre comment mettre à jour les étiquettes, les annotations et les teintures tout en minimisant les risques.

Ajouter ou modifier des étiquettes

Les étiquettes sont utilisées par les sélecteurs dans les Services, les Deployments et d’autres contrôleurs. Un changement d’étiquette négligent peut interrompre le routage du trafic ou la montée en charge. Pour mettre à jour les étiquettes en toute sécurité :

Utilisez kubectl get <ressource> <nom> -o yaml pour voir les étiquettes actuelles.

1. Identifier l’objet et les étiquettes souhaitées.
2. Appliquer un patch minimal avec kubectl label ou un patch de fusion stratégique.

Exemple : ajouter une étiquette d’environnement à un Deployment :

kubectl label deployment frontend env=production --overwrite

Sortie attendue :

deployment.apps/frontend labeled

Vérifiez :

kubectl get deployment frontend -o jsonpath='{.metadata.labels}' | jq

Attendu :

{
  "app": "frontend",
  "env": "production"
}

Ajouter ou modifier des annotations

Les annotations sont plus sûres à modifier car elles n’affectent pas les sélecteurs. Cependant, des outils comme les contrôleurs d’entrée ou les maillages de services peuvent lire les annotations pour la configuration. Avant de modifier une annotation, sachez quel outil la consomme.

Exemple : ajouter une annotation à un Service pour le schéma interne d’un équilibreur de charge AWS :

kubectl annotate service frontend service.beta.kubernetes.io/aws-load-balancer-internal="true"

Vérifiez :

kubectl get service frontend -o jsonpath='{.metadata.annotations}' | jq

Ajouter ou supprimer des teintures et des tolérances

Les teintures sont un contrôle au niveau du nœud. Elles doivent être appliquées aux nœuds et associées à des tolérances sur les pods qui doivent s’y exécuter. Une teinture mal appliquée peut évincer ou empêcher l’ordonnancement de charges de travail critiques.

Pour ajouter une teinture qui empêche tous les pods de s’ordonnancer sur un nœud à moins qu’ils n’aient une tolérance correspondante :

kubectl taint nodes node1 dedicated=experimental:NoSchedule

Attendu :

node/node1 tainted

Pour supprimer la teinture :

kubectl taint nodes node1 dedicated=experimental:NoSchedule-

Notez le trait d’union final après l’effet. Vérifiez les teintures du nœud :

kubectl get node node1 -o jsonpath='{.spec.taints}' | jq

Pour les pods, les tolérances sont déclarées dans la spécification du pod. Exemple d’extrait de tolérance :

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

Appliquez le manifeste du pod puis vérifiez que le pod est ordonnancé sur le nœud teinté :

kubectl get pod <nom-du-pod> -o wide

Valider avant d’appliquer en production

• Utilisez kubectl apply --dry-run=client -f manifest.yaml pour voir ce qui changerait sans appliquer.
• Pour les mises à jour critiques, utilisez une approche canari : mettez à jour une seule réplique ou un déploiement de test d’abord, observez, puis déployez.
• Conservez une copie du manifeste original ou utilisez kubectl get <ressource> -o yaml > backup.yaml avant les changements.

Vérification et diagnostic

Après avoir effectué des modifications, vous devez vérifier que l’état observé correspond à l’état voulu. Cette section donne des procédures de diagnostic pour les étiquettes, les annotations et les teintures.

Vérifier les sélecteurs d’étiquettes dans les contrôleurs

Un échec courant est un sélecteur de Service qui ne correspond plus aux pods après un changement d’étiquette. Pour vérifier :

1. Obtenez le sélecteur du Service :

kubectl get service frontend -o jsonpath='{.spec.selector}' | jq

1. Listez les pods avec ce sélecteur :

kubectl get pods -l app=frontend

Si aucun pod n’apparaît, le sélecteur est cassé. Corrigez les étiquettes des pods ou le sélecteur du Service.

1. Vérifiez les endpoints :

kubectl get endpoints frontend

Si la liste des endpoints est vide, aucun pod ne soutient le Service.

Vérifier la consommation des annotations par les outils

Pour les annotations utilisées par les contrôleurs d’entrée ou d’autres opérateurs, consultez les journaux de l’outil. Par exemple, pour Nginx Ingress :

kubectl logs -n ingress-nginx deployment/ingress-nginx-controller --tail=50

Cherchez les erreurs ou avertissements liés à l’annotation que vous avez modifiée. Si l’outil ne prend pas en charge l’annotation, il peut l’ignorer silencieusement ; vérifiez toujours la documentation.

Commandes de diagnostic pour les teintures et l’ordonnancement

Quand un pod n’est pas ordonnancé, utilisez kubectl describe pod pour voir les événements :

kubectl describe pod my-pod

Cherchez des messages comme :

Warning  FailedScheduling  45s (x3 over 2m)  default-scheduler  0/3 nodes are available: 1 node(s) had untolerated taint {dedicated: experimental}, 2 Insufficient cpu.

Cela vous indique que le pod n’a pas de tolérance pour la teinture dedicated=experimental. Ajoutez la tolérance ou supprimez la teinture selon le cas.

Vérifiez les teintures des nœuds et les tolérances avec :

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

Pour une vue détaillée des tolérances d’un pod :

kubectl get pod my-pod -o jsonpath='{.spec.tolerations}' | jq

Utiliser l’état du déploiement pour les Deployments

Si vous avez modifié des étiquettes sur un Deployment, vérifiez que le déploiement a réussi :

kubectl rollout status deployment/frontend

Attendu en cas de succès :

deployment "frontend" successfully rolled out

Si le déploiement se bloque, vérifiez l’état des pods et les événements :

kubectl get pods -l app=frontend
kubectl describe pod <nom-du-nouveau-pod>

Vérification rapide 2 : Selon la référence, laquelle des propositions suivantes N’EST PAS une étiquette prédéfinie que Kubernetes applique aux nœuds ?

• [ ] kubernetes.io/arch
• [ ] kubernetes.io/hostname
• [ ] topology.kubernetes.io/zone
• [ ] nfd.node.kubernetes.io/feature-labels

<details> <summary>Révéler la réponse</summary>

Les étiquettes prédéfinies sont kubernetes.io/arch, kubernetes.io/hostname, kubernetes.io/os, node.kubernetes.io/instance-type, topology.kubernetes.io/region et topology.kubernetes.io/zone. nfd.node.kubernetes.io/feature-labels est une annotation, pas une étiquette prédéfinie. </details>

Modes d’échec et récupération

Même des changements prudents peuvent échouer. Cette section couvre les scénarios d’échec courants et comment récupérer.

Étiquette manquante ou modifiée casse la découverte de Service

Symptôme : Les requêtes vers un Service renvoient 503 ou une connexion refusée. kubectl get endpoints n’affiche aucun endpoint.

Récupération :

1. Vérifiez le sélecteur du Service :

kubectl get service my-service -o jsonpath='{.spec.selector}' | jq

1. Listez les pods et leurs étiquettes :

kubectl get pods --show-labels

1. Si les pods n’ont pas l’étiquette requise, ajoutez-la :

kubectl label pods <nom-du-pod> app=my-app

1. Revérifiez les endpoints.

Teinture provoque une éviction accidentelle de pod

Symptôme : Des pods sont évincés d’un nœud après l’ajout d’une teinture.

Récupération :

1. Supprimez immédiatement la teinture si vous ne vouliez pas d’éviction :

kubectl taint nodes node1 dedicated=experimental:NoExecute-

1. Si l’éviction était voulue mais que vous devez ramener des pods spécifiques, ajoutez des tolérances à leurs spécifications et redéployez.

1. Vérifiez l’état des pods avec kubectl get pods -o wide.

Changement d’annotation casse le routage d’entrée

Symptôme : Après avoir modifié une annotation sur un Ingress ou un Service, le trafic s’arrête ou est mal routé.

Récupération :

1. Revenez à la valeur précédente de l’annotation en utilisant votre sauvegarde :

kubectl apply -f backup-ingress.yaml

1. Ou utilisez kubectl annotate pour supprimer la mauvaise annotation :

kubectl annotate ingress my-ingress bad.annotation-

1. Vérifiez les journaux du contrôleur d’entrée pour les erreurs.

Procédures de restauration pour les changements d’étiquettes/teintures

• Pour les étiquettes : utilisez kubectl label <ressource> <nom> <clé>- pour supprimer une étiquette, puis rajoutez correctement.
• Pour les teintures : utilisez le trait d’union final pour supprimer (par exemple, kubectl taint nodes node1 key=value:Effect-).
• Pour les annotations : utilisez kubectl annotate <ressource> <nom> <clé>- pour supprimer.
• Ayez toujours des sauvegardes ou un historique Git pour restaurer les manifestes.

Tester la récupération en préproduction avant la production

Simulez des échecs dans un cluster de préproduction. Par exemple, appliquez un changement d’étiquette cassant et entraînez-vous aux étapes de récupération. Documentez les commandes exactes et les sorties attendues afin que les ingénieurs d’astreinte puissent les suivre sous pression.

Liste de contrôle des opérations

Utilisez cette liste de contrôle comme vérification pré-vol et post-changement pour toute modification impliquant des étiquettes, des annotations ou des teintures.

Pré-changement

• [ ] Identifier la ressource, l’espace de noms et les étiquettes/annotations/teintures actuelles à l’aide de commandes en lecture seule.
• [ ] Prendre un instantané JSON ou YAML de la ressource avant les changements, stocké avec horodatage.
• [ ] Confirmer la version de Kubernetes et les dépendances d’outillage qui consomment les métadonnées.
• [ ] Déterminer le rayon d’impact : quels contrôleurs ou sélecteurs référencent ces métadonnées ? Utilisez kubectl get <ressource> -o yaml pour tracer.
• [ ] Préparer un plan de restauration avec des commandes exactes.

Pendant le changement

• [ ] Effectuer un petit changement à la fois.
• [ ] Préférer les commandes kubectl label, annotate ou taint pour des mises à jour chirurgicales ; éviter les remplacements massifs de manifestes sauf nécessité.
• [ ] Utiliser --dry-run=client pour prévisualiser quand c’est possible.
• [ ] Enregistrer le changement dans votre système de gestion des changements avec horodatage et opérateur.

Vérification post-changement

• [ ] Exécuter les contrôles de santé spécifiques au changement :
• Étiquettes : kubectl get pods -l <nouvelle-étiquette> et vérifier les endpoints.
• Annotations : vérifier les journaux de l’outil ou le comportement.
• Teintures : kubectl describe pod et kubectl get nodes -o wide pour confirmer l’ordonnancement.
• [ ] Surveiller pendant 15 à 30 minutes pour des évictions ou erreurs inattendues.
• [ ] En cas de succès, mettre à jour vos runbooks ou la documentation.
• [ ] En cas d’échec, restaurer immédiatement en utilisant vos commandes préparées, puis enquêter.

Exemple d’entrée de liste de contrôle pour un changement d’étiquette

Objectif : Ajouter l’étiquette env=staging au Deployment frontend dans l’espace de noms default.

Pré-changement :

kubectl get deployment frontend -o json | jq '.metadata.labels'

Changement :

kubectl label deployment frontend env=staging --overwrite

Vérifier :

kubectl get deployment frontend -o jsonpath='{.metadata.labels}' | jq

Attendu :

{
  "app": "frontend",
  "env": "staging"
}

Contrôle de santé :

kubectl rollout status deployment/frontend

Restaurer si nécessaire :

kubectl label deployment frontend env-

Conclusion

Les étiquettes Kubernetes, les annotations et les teintures sont essentielles pour organiser, configurer et contrôler les charges de travail, mais elles exigent des pratiques opérationnelles disciplinées. Une liste de contrôle des opérations de production garantit que les changements sont limités à la version, observables et réversibles dans la mesure du possible. Copier une commande sans vérifier les prérequis et la sortie attendue n’est pas une procédure d’exploitation.

Commencez par une vérification à faible risque : choisissez un changement d’étiquette, d’annotation ou de teinture, enregistrez l’état actuel, exécutez la commande documentée, comparez le résultat avec la sortie attendue et passez en revue les dépendances telles que les Pods, les Nœuds et les Deployments. Répétez ce cycle jusqu’à ce qu’il devienne routinier.

Un flux de travail technique fiable rend l’échec visible, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu’un incident ne force la décision. En appliquant les principes et les commandes de cet article, vous pouvez exploiter les contrôles de métadonnées Kubernetes avec confiance.

Prochaines étapes :

• Auditez vos étiquettes et annotations actuelles pour la cohérence en utilisant kubectl get all --show-labels.
• Définissez une convention de nommage et une documentation pour les étiquettes et annotations personnalisées.
• Testez un scénario de teinture/tolérance dans un cluster de préproduction pour comprendre le comportement d’ordonnancement.
• Automatisez la validation des métadonnées dans les pipelines CI/CD.

Rappelez-vous : observez, changez, vérifiez et récupérez.