Étiquettes, annotations et teintures Kubernetes : planification de capacité avec exemples pratiques

Introduction

Une planification de capacité Kubernetes efficace exige plus que la simple définition des requêtes CPU et mémoire. Les étiquettes, les annotations et les teintures sont les mécanismes fondamentaux qui contrôlent l'ordonnancement, l'organisation et le comportement opérationnel de vos charges de travail. Utilisés correctement, ils permettent un contrôle précis de l'emplacement des pods, de leur sélection pour les services et de la protection des nœuds contre les charges de travail inadaptées. Cet article fournit un guide pratique sur l'utilisation des étiquettes, des annotations et des teintures pour la planification de capacité, avec des exemples concrets et des commandes que vous pouvez exécuter dès aujourd'hui.

Que vous soyez un développeur préparant la production, un ingénieur DevOps optimisant l'utilisation du cluster ou un fondateur technique gérant l'infrastructure, comprendre ces primitives est essentiel pour une mise à l'échelle prévisible et une utilisation efficace des ressources. Nous couvrirons les bonnes pratiques, les pièges courants et les instructions étape par étape pour mettre en œuvre chaque concept, toujours dans une optique de sécurité opérationnelle et de réversibilité.

Inventaire de version et d'environnement

Avant d'apporter des modifications, établissez une base claire de votre environnement Kubernetes. Cet inventaire vous aide à comprendre ce avec quoi vous travaillez et réduit le risque d'appliquer des configurations incompatibles.

Composants pertinents et plage de versions :

• Version du cluster Kubernetes : 1.26 à 1.30 (les commandes et API peuvent différer dans les versions plus anciennes ou plus récentes)
• Version du client kubectl : identique ou dans une version mineure du serveur
• Runtime de conteneur : containerd 1.7+ ou CRI-O 1.28+
• Fournisseur cloud (le cas échéant) : AWS EKS, Azure AKS ou Google GKE

Prérequis :

• Un cluster Kubernetes en cours d'exécution avec accès administratif
• kubectl configuré avec le contexte kubeconfig correct
• Compréhension de base des objets Kubernetes tels que les Pods, les Deployments et les Nodes

Observation en lecture seule : Exécutez les commandes suivantes pour capturer l'état actuel sans rien modifier :

# Vérifier la version du cluster
kubectl version --short

# Lister 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

# Lister tous les pods avec leurs étiquettes
kubectl get pods --all-namespaces --show-labels

Exemple de sortie pour kubectl get nodes --show-labels :

NAME          STATUS   ROLES           AGE   VERSION   LABELS
node-1        Ready    control-plane   10d   v1.28.2   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,kubernetes.io/hostname=node-1,node-role.kubernetes.io/control-plane=
node-2        Ready    <none>          10d   v1.28.2   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,kubernetes.io/hostname=node-2
node-3        Ready    <none>          10d   v1.28.2   beta.kubernetes.io/arch=amd64,beta.kubernetes.io/os=linux,kubernetes.io/hostname=node-3

Plus petite modification justifiée : Ce n'est qu'après avoir documenté la base que vous devriez envisager une modification. Par exemple, si vous devez ajouter une étiquette à un nœud pour l'ordonnancement, c'est un changement minimal et réversible :

kubectl label node node-2 environment=production

Vérification : Après le changement, vérifiez qu'il a pris effet :

kubectl get node node-2 --show-labels | grep environment

La sortie attendue inclut environment=production.

Chemin de configuration sécurisé

Les étiquettes et annotations sont souvent ajoutées via des manifestes ou des commandes impératives. Pour garantir la sécurité, suivez un chemin structuré qui minimise les risques.

Périmètre du composant et de la version :

• Version de l'API Kubernetes pour les étiquettes/annotations : v1 (stable toutes versions)
• Teintures et tolérances : v1, mais sémantique inchangée depuis la 1.16

Prérequis :

• Assurez-vous d'avoir les autorisations RBAC nécessaires pour modifier les ressources cibles
• Pour les teintures de nœuds, vous avez besoin de cluster-admin ou équivalent

Observation en lecture seule : Avant d'ajouter ou de modifier des étiquettes ou annotations, listez celles existantes sur une ressource spécifique :

# Voir les étiquettes d'un déploiement
kubectl get deployment my-app -o jsonpath='{.metadata.labels}'

# Voir les annotations d'un pod
kubectl get pod my-app-abcde -o jsonpath='{.metadata.annotations}'

Plus petite modification justifiée : Ajoutez une étiquette à un déploiement avec kubectl label :

kubectl label deployment my-app app.kubernetes.io/version=v1.2.3

Ou ajoutez une annotation via patch :

kubectl annotate deployment my-app description="Service frontal pour portail client"

Vérification : Confirmez que l'étiquette/annotation a été appliquée :

kubectl get deployment my-app --show-labels
kubectl describe deployment my-app | grep Annotations

Rayon d'impact et récupération : Si vous devez revenir en arrière, retirez simplement l'étiquette ou l'annotation :

kubectl label deployment my-app app.kubernetes.io/version-
kubectl annotate deployment my-app description-

Notez le tiret final pour supprimer.

Vérification et diagnostics

Après avoir appliqué les changements de configuration, une vérification approfondie prévient les problèmes futurs. Voici comment diagnostiquer les problèmes courants liés aux étiquettes, annotations et teintures.

Scénario : Pod bloqué en attente (Pending) en raison d'une affinité de nœud non satisfaite

Supposons que vous ayez un déploiement avec un sélecteur de nœud :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cache
spec:
  replicas: 3
  selector:
    matchLabels:
      app: cache
  template:
    metadata:
      labels:
        app: cache
    spec:
      nodeSelector:
        disktype: ssd
      containers:
      - name: redis
        image: redis:7

Si aucun nœud n'a l'étiquette disktype=ssd, les pods resteront en attente. Diagnostiquez avec :

kubectl describe pod cache-xxxxx-xxxxx

Recherchez des événements comme :

Events:
  Type     Reason            Age   From               Message
  ----     ------            ----  ----               -------
  Warning  FailedScheduling  2m    default-scheduler  0/3 nodes are available: 3 node(s) didn't match Pod's node affinity/selector.

Commandes de diagnostic :

• kubectl get events --field-selector involvedObject.name=<nom-du-pod>
• kubectl logs <nom-du-pod> --previous si le pod a planté
• kubectl rollout status deployment/cache pour vérifier la progression du déploiement

Sortie attendue et récupération : Une fois que vous étiquetez un nœud avec disktype=ssd, le planificateur devrait y placer le pod. Vérifiez avec :

kubectl label node node-2 disktype=ssd
kubectl get pods -o wide

Le pod devrait maintenant afficher Running et NODE comme node-2.

Modes de défaillance et récupération

Comprendre les modes de défaillance courants vous aide à vous préparer et à réagir efficacement.

Mode de défaillance 1 : la teinture empêche l'ordonnancement

Si un nœud a une teinture comme key=value:NoSchedule, les pods sans tolérance correspondante ne seront pas planifiés dessus.

Exemple :

Teinture de nœud :

kubectl taint nodes node-1 dedicated=experimental:NoSchedule

Un pod sans tolérance ne sera pas planifié sur node-1. Pour autoriser un pod spécifique, ajoutez une tolérance :

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

Récupération : Si vous avez teinté un nœud accidentellement, retirez la teinture :

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

Mode de défaillance 2 : un décalage d'étiquette casse le routage du service

Un service sélectionne les pods en fonction des étiquettes. Si les étiquettes sur les pods et le sélecteur du service ne correspondent pas, le trafic n'atteindra pas les pods.

Exemple :

Service :

apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  selector:
    app: my-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 9376

Si le modèle de pod du déploiement a app: web au lieu de app: my-app, le service n'aura aucun endpoint. Diagnostiquez :

kubectl get endpoints my-service

Si les endpoints sont vides, vérifiez les étiquettes :

kubectl get pods -l app=my-app

Si aucune ressource n'est trouvée, le sélecteur est incorrect. Corrigez en mettant à jour les étiquettes du déploiement ou le sélecteur du service.

Récupération : Patchez le déploiement pour utiliser la bonne étiquette :

kubectl patch deployment my-deployment -p '{"spec":{"template":{"metadata":{"labels":{"app":"my-app"}}}}}'

Vérifiez ensuite que les endpoints apparaissent.

Liste de contrôle des opérations

Utilisez cette liste pour vous assurer d'avoir couvert tous les aspects lorsque vous travaillez avec des étiquettes, annotations et teintures pour la planification de capacité.

Liste de contrôle pour les changements de teinture de nœud :

• [ ] Identifier le(s) nœud(s) cible(s) et les teintures actuelles : kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints
• [ ] Déterminer l'effet : NoSchedule, PreferNoSchedule, NoExecute
• [ ] Évaluer l'impact : quels pods existants pourraient être évincés (pour NoExecute) ou non planifiés (pour NoSchedule)
• [ ] Appliquer la teinture avec une commande documentée, par exemple kubectl taint nodes node-3 dedicated=special-user:NoSchedule
• [ ] Vérifier que la teinture est présente : kubectl describe node node-3 | grep Taints
• [ ] Tester l'ordonnancement : déployez un pod avec et sans tolérance pour confirmer le comportement
• [ ] Documenter la teinture dans votre infrastructure as code (par exemple Terraform, Cluster API)
• [ ] Mettre en place des alertes de surveillance pour les pods non planifiables (par exemple en utilisant kube-state-metrics)

Liste de contrôle pour les changements d'étiquette sur les nœuds :

• [ ] Identifier l'objectif de l'étiquette (par exemple zone, type de matériel, environnement)
• [ ] Vérifier les étiquettes existantes : kubectl get node <nom> --show-labels
• [ ] Ajouter l'étiquette : kubectl label node <nom> <clé>=<valeur>
• [ ] Mettre à jour les sélecteurs de nœuds dans les charges de travail pour utiliser la nouvelle étiquette (si nécessaire)
• [ ] Vérifier l'ordonnancement : kubectl get pods -o wide pour voir le placement
• [ ] Revenir en arrière en cas de problème : supprimer l'étiquette avec kubectl label node <nom> <clé>-

Liste de contrôle pour les changements d'annotation :

• [ ] Déterminer si une annotation est nécessaire par rapport à une étiquette (les annotations servent aux métadonnées, pas à la sélection)
• [ ] Enregistrer les annotations actuelles : kubectl get <ressource> <nom> -o jsonpath='{.metadata.annotations}'
• [ ] Ajouter ou mettre à jour l'annotation : kubectl annotate <ressource> <nom> clé=valeur --overwrite
• [ ] Vérifier l'annotation : kubectl describe <ressource> <nom> | grep Annotations
• [ ] S'assurer que l'annotation est documentée dans le code/référentiel pour la reproductibilité

Conclusion

Les étiquettes, les annotations et les teintures sont des outils puissants pour la planification de capacité Kubernetes, mais ils doivent être utilisés avec précision et soin. En suivant l'approche systématique décrite dans cet article—commencer par un inventaire complet de l'environnement, appliquer des changements de configuration sûrs, vérifier avec des diagnostics et être prêt pour les modes de défaillance—vous pouvez maintenir un cluster robuste et efficace.

Rappelez-vous : observez toujours avant de modifier, limitez le rayon d'impact, vérifiez les résultats et documentez les chemins de récupération. Avec ces pratiques, vous pouvez exploiter les primitives Kubernetes pour optimiser l'utilisation des ressources, améliorer la prévisibilité de l'ordonnancement et réduire les surprises opérationnelles.

Comme prochaine étape, choisissez une amélioration à faible risque dans les listes de contrôle—par exemple, ajoutez une étiquette significative à un nœud et mettez à jour le nodeSelector d'un déploiement pour tester l'affinité. Enregistrez l'état actuel, appliquez le changement, vérifiez l'ordonnancement des pods, puis envisagez d'automatiser le processus avec des outils GitOps comme Argo CD ou Flux. Le chemin vers la maîtrise est itératif, et chaque petit pas sûr construit un environnement de production résilient.