E-NO
Kubernetes 8 min de lecture

Automatiser les étiquettes, annotations et teintes Kubernetes dans le CI/CD : un guide pratique

calendar_today Publié : 2026-11-17
update Dernière mise à jour : 2026-11-17
analytics Efficacité SEO : 100%
Illustration du guide technique pour « Automatiser les étiquettes, annotations et teintes Kubernetes dans le CI/CD : un guide pratique ».

Introduction

Les étiquettes (labels), annotations et teintes (taints) de Kubernetes sont essentielles pour organiser, décrire et contrôler les charges de travail. Les étiquettes sont des paires clé-valeur utilisées pour identifier et sélectionner des ressources. Les annotations stockent des métadonnées non identifiantes pour les outils et les humains. Les teintes sur les nœuds repoussent les pods à moins que ceux-ci n'aient des tolérances correspondantes. La gestion manuelle de ces champs de métadonnées devient source d'erreurs et d'incohérences à mesure que les clusters grandissent. Automatiser leur gestion via des pipelines CI/CD garantit la cohérence, réduit les erreurs humaines et permet des pratiques GitOps où l'état souhaité est versionné et auditable.

Ce guide montre comment automatiser ces ressources en toute sécurité, de l'inventaire de l'environnement à la vérification et à la restauration. Il s'adresse aux ingénieurs de plateforme, aux praticiens DevOps et à toute personne responsable de l'exploitation de clusters Kubernetes. Vous apprendrez à :

  • Inventorier votre environnement Kubernetes, y compris les versions et la topologie.
  • Définir un chemin de configuration sûr en utilisant des manifestes déclaratifs et kubectl.
  • Vérifier les changements avec des commandes et des sorties attendues.
  • Gérer les modes de défaillance courants et récupérer avec élégance.
  • Suivre une liste de contrôle opérationnelle pour un succès reproductible.

À la fin, vous disposerez d'un modèle concret et réutilisable pour gérer les étiquettes, annotations et teintes dans un pipeline CI/CD en toute confiance.

Inventaire des versions et de l'environnement

Avant d'automatiser, documentez votre environnement. Connaître la version de Kubernetes, les ressources d'API et les métadonnées existantes vous aide à éviter les problèmes de compatibilité et à planifier les changements. Cette section passe en revue les commandes clés.

Vérifier la version de Kubernetes

Exécutez la commande suivante pour vérifier les versions du client et du serveur :

kubectl version --short

Exemple de sortie :

Client Version: v1.25.0
Server Version: v1.24.3

Assurez-vous que votre client kubectl est compatible avec le cluster. Kubernetes prend en charge un écart de version d'une version mineure entre le client et le serveur, donc un client v1.25.0 fonctionne avec un serveur v1.24.3. Si l'écart est plus important, les fonctionnalités ou les ressources d'API peuvent ne pas se comporter comme prévu.

Inspecter les étiquettes et annotations existantes

Listez les étiquettes actuelles sur un espace de noms ou un déploiement pour comprendre les conventions de nommage :

kubectl get namespace default --show-labels

Exemple de sortie :

NAME      STATUS   AGE   LABELS
default   Active   10d   kubernetes.io/metadata.name=default

Pour un déploiement :

kubectl get deployment my-app -n default -o jsonpath='{.metadata.labels}'

Exemple de sortie :

{"app":"my-app","version":"v1"}

Pour voir les annotations, utilisez :

kubectl get deployment my-app -n default -o jsonpath='{.metadata.annotations}'

Cette sortie vous aide à comprendre les conventions existantes, par exemple si l'équipe utilise des étiquettes avec le préfixe app.kubernetes.io/ ou des clés personnalisées.

Examiner les teintes sur les nœuds

Listez les teintes sur tous les nœuds avec une sortie en colonnes personnalisées :

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

Exemple de sortie :

NAME     TAINTS
node-1   [map[effect:NoSchedule key:dedicated value:team-a]]
node-2   <none>

Cela montre que node-1 a une teinte dedicated=team-a:NoSchedule, ce qui signifie que les pods sans tolérance correspondante ne seront pas planifiés sur ce nœud.

Prérequis

  • Un cluster Kubernetes en cours d'exécution (version 1.19 ou ultérieure).
  • kubectl configuré avec les permissions appropriées. Vous avez besoin des permissions pour obtenir, patcher et étiqueter des ressources.
  • Un dépôt Git pour stocker les manifestes.
  • Un système CI/CD tel que Jenkins, GitLab CI, GitHub Actions ou Argo CD.
  • Facultatif : Helm ou Kustomize pour la création de modèles et la gestion des surcouches. Ce guide utilise Kustomize pour la gestion des étiquettes et annotations.

Question rapide 1 sur 2

Selon le passage, quelle est la principale distinction entre les labels et les annotations ?

Le passage indique : « Les labels peuvent être utilisés pour sélectionner des objets et pour trouver des collections d'objets qui satisfont certaines conditions. En revanche, les annotations ne sont pas utilisées pour identifier et sélectionner des objets. »

Chemin de configuration sûr

Un chemin de configuration sûr signifie appliquer les changements de manière incrémentale et avec révision. Utilisez des manifestes déclaratifs stockés dans le contrôle de version et appliquez-les via le CI/CD avec des vérifications en mode simulation (dry-run) et des comparaisons (diff). Cette section couvre trois approches : Kustomize pour les étiquettes et annotations, le patching YAML pour les teintes, et un exemple complet de pipeline CI/CD.

Utiliser Kustomize pour la gestion des étiquettes et annotations

Kustomize est un outil de gestion de configuration natif de Kubernetes qui permet d'appliquer des étiquettes et annotations communes à toutes les ressources sans modifier chaque manifeste. Il est intégré à kubectl avec kubectl apply -k. Créez un fichier kustomization.yaml :

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
commonLabels:
  team: platform
  environment: staging
commonAnnotations:
  owner: platform-team
resources:
  - deployment.yaml

Cela applique les étiquettes team: platform et environment: staging, et l'annotation owner: platform-team à chaque ressource listée dans resources. Les champs commonLabels et commonAnnotations ajoutent ou mettent à jour ces champs de métadonnées sur toutes les ressources. Cependant, commonLabels écrasera les étiquettes existantes ayant la même clé ; si vous devez en préserver certaines, utilisez une approche plus ciblée comme patchesStrategicMerge.

Appliquez avec :

kubectl apply -k .

Gérer les teintes via YAML dans GitOps

Les teintes sont des configurations au niveau des nœuds. Vous pouvez les définir de manière déclarative en patchant les nœuds avec du YAML. Exemple de fichier de patch de nœud node-taints.yaml :

spec:
  taints:
  - key: dedicated
    value: team-a
    effect: NoSchedule

Appliquez ce patch à un nœud spécifique :

kubectl patch node node-1 --patch-file node-taints.yaml

Cependant, le patch remplace toute la liste des teintes. Si le nœud a déjà d'autres teintes, elles seront supprimées à moins de les inclure dans le patch. Une méthode plus sûre consiste à utiliser kubectl taint dans un script, qui ajoute ou met à jour une seule teinte sans affecter les autres :

kubectl taint nodes node-1 dedicated=team-a:NoSchedule

Dans un pipeline CI/CD, utilisez une variable pour le nom du nœud, comme $NODE_NAME. Assurez-vous que le pipeline a la permission de patcher les nœuds.

Exemple de pipeline CI/CD

Voici une étape de pipeline GitLab CI pour appliquer les étiquettes et annotations avec Kustomize, avec une étape de validation et une étape d'application manuelle :

stages:
  - validate
  - apply

validate:
  stage: validate
  script:
    - kubectl apply --dry-run=client -k . -o yaml > dry-run.yaml
    - cat dry-run.yaml
  only:
    - main

apply:
  stage: apply
  script:
    - kubectl apply -k .
  when: manual
  only:
    - main

Ce pipeline valide d'abord avec un dry-run lorsqu'un commit est poussé sur main. La sortie du dry-run est enregistrée et affichée pour révision. Le job d'application est manuel, ce qui signifie qu'un humain doit l'approuver avant que les changements ne soient appliqués. Cette séparation réduit le risque de changements involontaires.

Pour les teintes, vous pourriez ajouter un job séparé qui exécute la commande kubectl taint sur un nœud spécifique. Utilisez des variables d'environnement pour les noms de nœuds et les valeurs de teinte.

Choix d'implémentation limités

  • Commencez par un seul espace de noms ou une seule charge de travail pour limiter le rayon d'impact.
  • Utilisez des pipelines séparés pour les métadonnées (étiquettes/annotations) et les teintes, car elles affectent différents types de ressources et ont des profils de risque différents.
  • Évitez de gérer les teintes pour tous les nœuds à la fois ; ciblez des nœuds spécifiques et validez l'impact sur la planification.

Vérification et diagnostics

Après avoir appliqué les changements, vérifiez qu'ils ont pris effet et qu'ils n'ont pas cassé les charges de travail. Cette section fournit des commandes et des sorties attendues.

Vérifier les étiquettes et annotations

Vérifiez les étiquettes d'un déploiement :

kubectl get deployment my-app -n default -o jsonpath='{.metadata.labels}'

La sortie attendue inclut les nouvelles étiquettes, par exemple :

{"app":"my-app","team":"platform"}

Pour les annotations :

kubectl get deployment my-app -n default -o jsonpath='{.metadata.annotations}'

La sortie attendue inclut owner: platform-team.

Vérifier les teintes

Listez les teintes sur un nœud :

kubectl describe node node-1 | grep Taints

Exemple de sortie :

Taints:             dedicated=team-a:NoSchedule

Vérifier la planification des pods

Assurez-vous que les pods ne sont pas bloqués en attente à cause des teintes. Vérifiez le statut des pods :

kubectl get pods -n default

Si un pod est en attente, décrivez-le pour voir les événements liés aux teintes :

kubectl describe pod my-pod

Recherchez des événements comme :

0/3 nodes are available: 3 node(s) had taint {dedicated: team-a}, that the pod didn't tolerate.

Cela indique que le pod n'a pas de tolérance pour la teinte. Vous devez soit ajouter une tolérance à la spécification du pod, soit supprimer la teinte si elle n'est plus nécessaire.

Commandes de vérification et résultats attendus

Le tableau suivant résume les commandes de vérification clés :

VérificationCommandeRésultat attendu
Étiquettes sur le déploiementkubectl get deployment my-app -o jsonpath='{.metadata.labels}'Inclut les nouvelles étiquettes
Annotations sur le podkubectl get pod my-pod -o jsonpath='{.metadata.annotations}'Inclut les nouvelles annotations
Teintes sur le nœudkubectl describe node node-1 | grep TaintsAffiche la teinte clé=valeur : effet
Planification des podskubectl get podsPods en cours d'exécution, pas en attente

Pièges courants et comment les éviter

L'automatisation des métadonnées Kubernetes peut mal tourner de plusieurs façons. Voici les pièges les plus courants, pourquoi ils surviennent et comment les éviter ou s'en remettre.

Écraser les étiquettes existantes avec Kustomize commonLabels

Kustomize commonLabels remplace les étiquettes existantes ayant la même clé. Par exemple, si un déploiement a déjà app: my-app et que vous ajoutez app: your-app à commonLabels, l'ancienne valeur est écrasée. Cela peut casser les sélecteurs. Pour éviter cela, utilisez commonLabels uniquement pour les clés que vous n'avez pas besoin de préserver, ou utilisez patchesStrategicMerge pour ajouter des étiquettes sans écraser. Pour récupérer, annulez le changement et réappliquez l'état précédent depuis l'historique Git.

Supprimer accidentellement toutes les teintes avec kubectl patch

Lorsque vous utilisez kubectl patch node avec une liste complète de taints, vous remplacez toute la liste. Si vous ne spécifiez qu'une seule teinte dans le patch, toutes les autres teintes sont supprimées. Cela peut laisser des nœuds sans teintes critiques comme node-role.kubernetes.io/master:NoSchedule. Pour éviter cela, utilisez kubectl taint au lieu de patcher, ou incluez soigneusement toutes les teintes existantes dans le patch. Pour récupérer, réajoutez immédiatement les teintes manquantes avec kubectl taint nodes <node> <key>=<value>:<effect>.

Appliquer des teintes sans vérifier les tolérances des pods

Ajouter une teinte, en particulier une teinte NoExecute, peut évincer les pods en cours d'exécution qui n'ont pas de tolérances correspondantes. Vérifiez toujours quels pods s'exécutent sur un nœud avant d'ajouter une teinte, et ayez un plan de restauration. Utilisez kubectl get pods --all-namespaces --field-selector spec.nodeName=node-1 pour voir les pods affectés. Pour récupérer, supprimez la teinte avec kubectl taint nodes node-1 dedicated=team-a:NoSchedule- (notez le signe moins à la fin).

Échecs de pipeline dus à des permissions RBAC insuffisantes

Le compte de service utilisé par votre pipeline CI/CD a besoin de permissions pour modifier les ressources. Pour les étiquettes et annotations, vous avez besoin de patch et update sur les déploiements, les espaces de noms ou d'autres ressources. Pour les teintes, vous avez besoin de patch sur les nœuds. Si le pipeline échoue, vérifiez le message d'erreur et ajustez les rôles RBAC. Exemple de ClusterRole pour la gestion des teintes :

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: node-tainter
rules:
- apiGroups: [""]
  resources: ["nodes"]
  verbs: ["get", "list", "patch", "update"]

Ensuite, liez ce rôle au compte de service utilisé par le pipeline.

Question rapide 2 sur 2

Parmi les propositions suivantes, laquelle n'est PAS listée comme exemple d'information pouvant être enregistrée dans les annotations ?

Le passage liste des exemples tels que les informations de build/release, des pointeurs vers la journalisation/la surveillance, et des numéros de téléphone, mais ne mentionne pas les limites ou les requêtes de ressources.

Modes de défaillance et récupération

Au-delà des pièges courants, préparez-vous à des scénarios de défaillance spécifiques.

Incohérence du dry-run

Si la sortie du dry-run ne correspond pas aux attentes, examinez les manifestes et la configuration Kustomize. Pour les teintes, assurez-vous que le nom du nœud est correct et que la syntaxe de la teinte est valide. Les erreurs courantes incluent l'oubli du champ effet ou l'utilisation d'un format de clé invalide.

Suppression accidentelle de teinte

Supprimer une teinte de manière incorrecte peut permettre à des pods non intentionnels de se placer sur un nœud. Pour récupérer, réappliquez la teinte :

kubectl taint nodes node-1 dedicated=team-a:NoSchedule

Vérifiez quels pods sont maintenant sur le nœud et décidez s'ils devraient y être.

Écrasement d'étiquettes

Appliquer des étiquettes avec kubectl apply peut écraser les étiquettes existantes si on ne fait pas attention. Utilisez kubectl label --overwrite uniquement lorsque c'est intentionnel. Pour annuler, réappliquez l'ensemble d'étiquettes précédent depuis l'historique Git. Par exemple, si vous avez accidentellement changé app de my-app à other, exécutez :

kubectl label deployment my-app -n default app=my-app --overwrite

Stratégies de restauration

  • Pour les changements Kustomize, annulez le commit dans Git et relancez le pipeline. Le job d'application devrait reprendre l'état annulé.
  • Pour les teintes, utilisez kubectl taint nodes node-1 dedicated=team-a:NoSchedule- pour supprimer, puis réajoutez si nécessaire.
  • Conservez des sauvegardes des configurations de teintes de nœuds dans le contrôle de version. Envisagez de stocker la configuration des nœuds dans un dépôt Git et d'utiliser un outil GitOps comme Argo CD pour l'appliquer.

Débogage des échecs de pipeline

Si le pipeline échoue à l'étape d'application, vérifiez d'abord le message d'erreur. Causes courantes :

  • Syntaxe YAML invalide.
  • Permissions RBAC manquantes.
  • Connectivité réseau au cluster.
  • Incompatibilité de version Kustomize.

Examinez les journaux du pipeline et exécutez les commandes localement pour reproduire le problème.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant et après l'application des changements. Attribuez un propriétaire pour chaque élément afin d'assurer la responsabilité. Le propriétaire doit être une personne nommée, pas une équipe. Révisez cette liste de contrôle chaque semaine lors d'une réunion de gestion des changements, ou avant chaque version.

ÉlémentPropriétaireFréquence
Vérifier les versions de Kubernetes et kubectlResponsable plateforme : Alex JohnsonAvant chaque changement
Examiner les étiquettes, annotations et teintes actuellesIngénieur DevOps : Sam LeeAvant chaque changement
Définir les changements souhaités dans les manifestes ou scriptsPropriétaire de l'application : Priya ShahAvant chaque changement
Tester avec kubectl apply --dry-run=client et inspecter la sortieApprobateur du pipeline CI/CD : Chris ChenAvant chaque changement
Appliquer les changements de manière limitée (par exemple, un espace de noms)Opérateur de déploiement : Dana WhiteAu moment de l'application
Vérifier avec les commandes kubectl get et describeIngénieur QA : Jordan PatelAprès l'application
Vérifier la planification des pods et la santé de l'applicationSRE de garde : Taylor KimAprès l'application, et pendant les 24 heures suivantes
Documenter les changements et les étapes de restaurationRédacteur technique : Morgan DavisAprès chaque changement
Surveiller tout comportement inattenduResponsable observabilité : Riley GarciaEn continu pendant 48 heures
Revoir et mettre à jour la liste de contrôle elle-mêmeResponsable plateforme : Alex JohnsonMensuellement

Cette liste de contrôle transforme le processus en une routine reproductible et auditable.

Conclusion

Automatiser les étiquettes, annotations et teintes Kubernetes via le CI/CD apporte cohérence et sécurité à la gestion des clusters. En suivant une approche structurée - inventaire, configuration sûre, vérification et récupération - vous pouvez réduire les erreurs et accélérer les déploiements. Commencez petit avec une seule charge de travail, validez avec des dry-runs et étendez progressivement. Utilisez le contrôle de version pour tous les changements afin de permettre l'auditabilité et la restauration. Avec ces pratiques, vous pouvez intégrer efficacement la gestion des métadonnées et des teintes dans votre flux de travail GitOps.

Prochaines étapes :

  • Mettre en œuvre un pipeline pilote pour un seul déploiement.
  • Intégrer la gestion des teintes de nœuds à l'automatisation du cycle de vie des nœuds.
  • Explorer les moteurs de politiques comme Open Policy Agent (OPA) pour appliquer les normes d'étiquettes et de teintes.

En adoptant ces pratiques, vous passez de modifications manuelles ponctuelles à un processus contrôlé et auditable qui évolue avec vos opérations Kubernetes.

Recherches connexes

Score de qualité de l’article

Utilité pour le lecteur 100%
  • check_circle Guide prêt à lire
  • check_circle Exemples pratiques inclus
  • check_circle URL d’article optimisée pour le SEO