## 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 : ```bash 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 : ```bash 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 : ```bash 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 : ```bash 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 ` affiche les événements, les étiquettes et les tolérances. Utilisez `kubectl logs --previous` pour diagnostiquer une boucle de crash, et `kubectl rollout status deployment/` pour confirmer qu'un déploiement est terminé. **Commande clé :** ```bash kubectl describe 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 :** ```bash kubectl label pod mon-pod environment=staging ``` Vérifiez qu'elle a pris effet : ```bash kubectl get pod mon-pod --show-labels ``` Si l'étiquette existe déjà, utilisez `--overwrite` : ```bash kubectl label pod mon-pod environment=production --overwrite ``` **Ajouter une annotation :** ```bash kubectl annotate pod mon-pod example.com/owner="platform-team" ``` Affichez les annotations : ```bash kubectl get pod mon-pod -o jsonpath='{.metadata.annotations}' ``` **Ajouter une teinture à un nœud :** ```bash 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 : ```bash kubectl describe node node1 | grep Taints ``` Sortie attendue : ``` Taints: dedicated=experimental:NoSchedule ``` **Exemples de simulation :** ```bash 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 : ```bash 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`) : ```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 : ```bash kubectl apply -f deploy.yaml ``` Vérifiez les pods : ```bash 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 : ```bash kubectl describe 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` : ```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 : ```bash kubectl apply -f toleration-pod.yaml ``` Vérifiez où il s'est planifié : ```bash 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 : ```bash 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 : ```bash kubectl get 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 :** ```bash 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 :** ```bash 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 : ```bash 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 : ```bash kubectl taint nodes node1 dedicated=experimental:NoExecute- ``` 3. Si les pods sont en CrashLoopBackOff, vérifiez les journaux : ```bash kubectl logs --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. | Étape | Action | Exemple de commande | Responsable | Fréquence de révision | |--------|--------|---------------------|-------------|----------------------| | 1 | Identifier les ressources affectées | `kubectl get pods,deployments,nodes` | Ingénieur plateforme (ex. Priya Shah) | Avant chaque changement | | 2 | Sauvegarder les étiquettes, annotations, teintures actuelles | `kubectl get nodes -o yaml > nodes-backup.yaml` | Ingénieur plateforme | Avant chaque changement | | 3 | Valider la syntaxe YAML | `kubectl apply --dry-run=client -f changes.yaml` | Ingénieur plateforme | Avant chaque changement | | 4 | Appliquer le changement | `kubectl apply -f changes.yaml` ou `kubectl label ...` | Ingénieur plateforme | Au moment du changement | | 5 | Vérifier le changement | `kubectl describe ` ou `kubectl get -o yaml` | Ingénieur plateforme | Immédiatement après | | 6 | Tester le comportement de la charge de travail | `kubectl get pods -o wide` et vérifier les événements | Responsable QA (ex. Marcus Chen) | Dans l'heure | | 7 | Documenter le changement et les étapes de restauration | Mettre à jour le runbook ou le wiki | Ingénieur plateforme | Le jour même | | 8 | Examiner l'impact sur la capacité du cluster et la répartition des pods | `kubectl top nodes` et `kubectl get pods -A` | Responsable SRE (ex. Aisha Patel) | Hebdomadaire | 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 : ```bash 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.