Étiquettes, annotations et teintures Kubernetes : architecture et opérations pratiques

Introduction

Les étiquettes, les annotations et les teintures sont des primitives Kubernetes essentielles qui contrôlent la manière dont les objets sont sélectionnés, décrits et planifiés. Les étiquettes sont des paires clé-valeur utilisées pour regrouper et sélectionner des ressources. Les annotations stockent des métadonnées non identifiantes, souvent pour l'intégration d'outils. Les teintures repoussent les pods des nœuds à moins que les pods aient des tolérances correspondantes. Ensemble, ces mécanismes permettent un placement précis des charges de travail, une visibilité opérationnelle et une gouvernance de l'infrastructure.

Cet article donne aux développeurs, aux ingénieurs DevOps et aux équipes techniques de startups une compréhension pratique de ces primitives. Vous verrez comment les étiquettes pilotent les sélecteurs, comment les annotations portent le contexte opérationnel et comment les teintures et tolérances empêchent ou autorisent la planification. Chaque section comprend des commandes réelles, des sorties attendues et des étapes de récupération. L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, éviter les secrets codés en dur, vérifier les résultats et documenter les chemins de récupération.

Inventaire de la version et de l'environnement

Avant de modifier les étiquettes, annotations ou teintures, confirmez la version de votre cluster et votre niveau d'accès. Ces fonctionnalités sont stables dans toutes les versions modernes de Kubernetes, mais la sortie des commandes et les options peuvent varier. Exécutez :

kubectl version --short

La sortie attendue affiche les versions du client et du serveur, par exemple :

Client Version: v1.27.3
Server Version: v1.27.3

Vérifiez vos autorisations avec :

kubectl auth can-i get nodes
kubectl auth can-i patch nodes

Si les deux renvoient yes, vous pouvez voir et modifier les teintures au niveau du nœud. Sinon, demandez à votre administrateur de cluster le rôle à privilège minimal nécessaire.

Avant de changer quoi que ce soit, capturez l'état actuel. Par exemple, listez tous les nœuds avec leurs étiquettes et teintures :

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

Enregistrez la sortie dans un fichier pour la restauration. Une approche simple :

kubectl get nodes -o yaml > nodes-backup-$(date +%Y%m%d-%H%M%S).yaml

Cela vous permet de restaurer les étiquettes ou les teintures en cas de problème.

Vérification pratique : Exécutez kubectl get pods -o wide pour voir le placement des pods. Ensuite, kubectl describe pod <nom-du-pod> affiche les événements, les étiquettes et les tolérances. Utilisez kubectl logs <nom-du-pod> --previous pour diagnostiquer une boucle de crash, et kubectl rollout status deployment/<nom> pour confirmer qu'un déploiement est terminé.

Commande clé :

kubectl describe pod <nom-du-pod> | grep -A5 Tolérations

Cela montre les tolérances existantes. Comparez-les avec les teintures des nœuds avant de modifier la planification.

Chemin de configuration sûr

Les étiquettes et les annotations sont simples à modifier, mais des étiquettes incorrectes peuvent casser les sélecteurs et déconnecter les services des pods. Les teintures peuvent perturber les charges de travail en cours si elles sont appliquées négligemment. Suivez un chemin sûr et réversible :

1. Observez les étiquettes, annotations et teintures actuelles.
2. Identifiez le plus petit changement nécessaire.
3. Testez dans un espace de noms non productif ou sur un seul nœud d'abord.
4. Appliquez le changement avec une simulation pour valider la syntaxe YAML.
5. Sauvegardez la configuration d'origine.
6. Appliquez le changement et vérifiez.
7. Ayez une commande de restauration prête.

Ajouter une étiquette à un pod :

kubectl label pod mon-pod environment=staging

Vérifiez qu'elle a pris effet :

kubectl get pod mon-pod --show-labels

Si l'étiquette existe déjà, utilisez --overwrite :

kubectl label pod mon-pod environment=production --overwrite

Ajouter une annotation :

kubectl annotate pod mon-pod example.com/owner="platform-team"

Affichez les annotations :

kubectl get pod mon-pod -o jsonpath='{.metadata.annotations}'

Ajouter une teinture à un nœud :

kubectl taint nodes node1 dedicated=experimental:NoSchedule

Cette teinture empêche les nouveaux pods de se planifier sur node1 à moins qu'ils ne la tolèrent. Vérifiez :

kubectl describe node node1 | grep Taints

Sortie attendue :

Taints:             dedicated=experimental:NoSchedule

Exemples de simulation :

kubectl taint nodes node1 dedicated=experimental:NoSchedule --dry-run=client -o yaml

Cela prévisualise le changement sans l'appliquer. Pour des changements complexes, utilisez kubectl apply --dry-run=server pour valider contre le serveur d'API.

Restauration :

Pour supprimer la teinture :

kubectl taint nodes node1 dedicated-

Notez le trait d'union final après la clé, qui supprime la teinture quelle que soit la valeur ou l'effet.

Vérification et diagnostics

Après tout changement, vérifiez que l'état souhaité correspond à l'état réel.

Vérification des étiquettes

Créez un déploiement avec une étiquette spécifique, puis vérifiez que les pods en héritent.

Exemple de manifeste de déploiement (deploy.yaml) :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
    tier: frontend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
        tier: frontend
    spec:
      containers:
      - name: nginx
        image: nginx:1.25

Appliquez-le :

kubectl apply -f deploy.yaml

Vérifiez les pods :

kubectl get pods -l app=web --show-labels

La sortie attendue montre trois pods, chacun avec les étiquettes app=web,tier=frontend.

Vérification des annotations

Inspectez les annotations sur un pod en cours d'exécution :

kubectl describe pod <nom-du-pod> | grep Annotations -A2

Si vous avez défini une annotation via kubectl annotate, confirmez qu'elle apparaît.

Vérification des teintures et tolérances

Créez un pod avec une tolérance pour la teinture dedicated=experimental:NoSchedule. Enregistrez ceci sous toleration-pod.yaml :

apiVersion: v1
kind: Pod
metadata:
  name: tolerant-pod
spec:
  containers:
  - name: nginx
    image: nginx:1.25
  tolerations:
  - key: "dedicated"
    operator: "Equal"
    value: "experimental"
    effect: "NoSchedule"

Appliquez :

kubectl apply -f toleration-pod.yaml

Vérifiez où il s'est planifié :

kubectl get pod tolerant-pod -o wide

Si la teinture est sur node1, le pod devrait s'exécuter sur node1. Si aucun nœud ne correspond, il peut rester en attente (Pending). Décrivez-le pour voir les événements :

kubectl describe pod tolerant-pod

Les événements montreront pourquoi la planification a échoué ou réussi.

Diagnostics avancés

Utilisez kubectl get avec -o json pour une inspection détaillée :

kubectl get pod <nom-du-pod> -o json | jq '.metadata.labels, .metadata.annotations, .spec.tolerations'

Cela imprime les trois en une seule commande. Installez jq si nécessaire.

Modes de défaillance et récupération

Les défaillances courantes concernent les incohérences d'étiquettes, les tolérances manquantes ou les teintures qui expulsent les pods de manière inattendue.

Incohérence d'étiquettes

Symptôme : Un service n'achemine pas le trafic vers les pods, ou un sélecteur de déploiement ne correspond pas aux étiquettes des pods.

Cause : Le matchLabels dans le sélecteur d'un déploiement doit correspondre exactement aux étiquettes du modèle de pod. Si vous modifiez l'un sans l'autre, le déploiement ne peut pas gérer les pods.

Exemple :

kubectl set selector deployment web app=webapp

Cela modifie le sélecteur du déploiement mais pas le modèle de pod. Le déploiement ne trouvera alors pas ses pods et peut en créer de nouveaux avec l'ancienne étiquette, causant de la confusion.

Récupération :

kubectl edit deployment web

Corrigez manuellement le sélecteur et les étiquettes du modèle de pod pour qu'ils soient identiques. Ou recréez le déploiement avec un manifeste corrigé.

Tolérance manquante

Symptôme : Un pod reste en attente avec un événement comme :

0/3 nodes are available: 1 node(s) had untolerated taint {dedicated: experimental}, 2 node(s) didn't match Pod's node affinity.

Cause : Le pod ne tolère pas la teinture sur le seul nœud approprié, ou il a des contraintes d'affinité de nœud qui ne peuvent pas être satisfaites.

Récupération :

Option 1 : Ajoutez une tolérance à la spécification du pod. Option 2 : Supprimez la teinture du nœud si elle n'est plus nécessaire :

kubectl taint nodes node1 dedicated-

Option 3 : Ajustez l'affinité de nœud pour autoriser d'autres nœuds.

Expulsion involontaire due à une teinture

Symptôme : Des pods en cours d'exécution sont expulsés ou terminés après l'ajout d'une teinture avec l'effet NoExecute.

Cause : Les teintures NoExecute expulsent les pods existants qui ne les tolèrent pas.

Récupération :

1. Ajoutez rapidement une tolérance au déploiement affecté, ou supprimez la teinture.
2. Pour supprimer la teinture :

kubectl taint nodes node1 dedicated=experimental:NoExecute-

1. Si les pods sont en CrashLoopBackOff, vérifiez les journaux :

kubectl logs <nom-du-pod> --previous

Erreurs d'écrasement d'étiquettes

Symptôme : La valeur d'une étiquette existante a changé de manière inattendue.

Cause : Utilisation de kubectl label --overwrite sans vérifier la valeur actuelle.

Récupération : Remettez l'étiquette à sa valeur d'origine. Enregistrez toujours les étiquettes actuelles avant les modifications.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour tout changement impliquant des étiquettes, des annotations ou des teintures.

Chaque étape a un seul responsable désigné pour éviter la dilution des responsabilités. Pour les petites équipes, l'ingénieur plateforme peut assumer toutes les étapes, mais le responsable doit être explicite.

Pièges courants et comment les éviter

1. Confondre les étiquettes avec les annotations

Erreur : Utiliser des étiquettes pour des métadonnées qui ne sont pas nécessaires à la sélection, ou utiliser des annotations pour la sélection.

Pourquoi cela arrive : Les deux sont des paires clé-valeur, mais leurs objectifs diffèrent. Les sélecteurs ne fonctionnent qu'avec les étiquettes.

Évitement : Utilisez les étiquettes pour le regroupement et la sélection (par ex., app, environment). Utilisez les annotations pour les données d'outillage, les informations de build ou les coordonnées, comme example.com/owner: "platform-team".

2. Oublier que les teintures et tolérances ne sont pas de l'affinité de nœud

Erreur : Supposer que les teintures seules planifieront les pods sur des nœuds spécifiques.

Pourquoi cela arrive : Les teintures repoussent les pods ; elles ne les attirent pas. Vous avez besoin d'une affinité de nœud ou d'un nodeSelector pour attirer les pods.

Évitement : Combinez les teintures et tolérances avec l'affinité de nœud pour un contrôle précis. Exemple : teintez un nœud avec gpu=true:NoSchedule, et ayez des pods avec une tolérance pour cette teinture plus un nodeSelector pour gpu=true.

3. Utiliser des teintures NoExecute sans test

Erreur : Appliquer une teinture NoExecute à un nœud de production et expulser immédiatement tous les pods non tolérants.

Pourquoi cela arrive : NoExecute expulse les pods existants qui manquent de tolérances, pas seulement les nouveaux pods.

Évitement : Testez dans un environnement de préproduction. Si vous devez utiliser NoExecute en production, ajoutez d'abord des tolérances à toutes les charges de travail qui doivent rester, puis appliquez la teinture progressivement. Utilisez une fenêtre de maintenance.

4. Syntaxe de sélecteur d'étiquettes incorrecte

Erreur : Utiliser selector au lieu de matchLabels dans les spécifications de déploiement, ou utiliser le mauvais opérateur dans les sélecteurs en ligne de commande.

Pourquoi cela arrive : Kubernetes prend en charge plusieurs syntaxes de sélecteur (matchLabels, matchExpressions, option -l), et il est facile de les mélanger.

Évitement : Pour les déploiements et les services, utilisez toujours matchLabels pour une sélection basée sur l'égalité. Pour une logique complexe, utilisez matchExpressions avec des opérateurs explicites (In, NotIn, Exists, DoesNotExist). Testez avec kubectl get pods -l key=value avant de référencer dans un manifeste.

5. Abuser des annotations pour des données critiques

Erreur : Stocker des informations sensibles (mots de passe, jetons) dans les annotations.

Pourquoi cela arrive : Les annotations sont pratiques et visibles avec kubectl describe, donc les gens en abusent.

Évitement : Utilisez les Secrets Kubernetes pour les données sensibles. Les annotations ne doivent contenir que des métadonnées non sensibles. Ne mettez jamais d'informations d'identification dans les étiquettes ou les annotations.

6. Ne pas sauvegarder les teintures de nœud avant les modifications

Erreur : Perdre la trace des teintures d'origine après les avoir supprimées, rendant la restauration impossible.

Pourquoi cela arrive : Les teintures ne sont pas versionnées, et kubectl describe ne montre que l'état actuel.

Évitement : Exportez toujours le YAML du nœud avant de modifier les teintures :

kubectl get nodes node1 -o yaml > node1-backup.yaml

Stockez les sauvegardes dans un système de contrôle de version pour l'auditabilité.

Conclusion

Les étiquettes, les annotations et les teintures sont fondamentales pour les opérations Kubernetes. Utilisées correctement, elles offrent une organisation robuste des charges de travail, des métadonnées opérationnelles et un contrôle de planification. Mal utilisées, elles provoquent des pannes et des cauchemars de débogage.

Commencez par une vérification à faible risque : choisissez un changement d'étiquette ou d'annotation, enregistrez l'état actuel, appliquez-le avec une simulation, vérifiez et revenez en arrière si nécessaire. Ensuite, expérimentez avec les teintures et tolérances dans un espace de noms non productif.

Un flux de travail fiable rend les défaillances visibles, protège les valeurs sensibles, limite les changements aux ressources prévues et définit la récupération avant un incident. En suivant les pratiques de cet article, vous pouvez opérer Kubernetes avec confiance et précision. Comme prochaines étapes, explorez l'affinité/anti-affinité de nœud, les définitions de ressources personnalisées et les contrôleurs d'admission pour construire sur la base des étiquettes, des annotations et des teintures.

Pour un apprentissage plus approfondi, consultez la documentation officielle de Kubernetes sur les étiquettes et sélecteurs, les annotations, et les teintures et tolérances. Entraînez-vous dans un cluster local comme minikube ou kind pour développer la mémoire musculaire sans risque de production.