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).
kubectlconfiguré 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.
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érification | Commande | Résultat attendu |
|---|---|---|
| Étiquettes sur le déploiement | kubectl get deployment my-app -o jsonpath='{.metadata.labels}' | Inclut les nouvelles étiquettes |
| Annotations sur le pod | kubectl get pod my-pod -o jsonpath='{.metadata.annotations}' | Inclut les nouvelles annotations |
| Teintes sur le nœud | kubectl describe node node-1 | grep Taints | Affiche la teinte clé=valeur : effet |
| Planification des pods | kubectl get pods | Pods 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.
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ément | Propriétaire | Fréquence |
|---|---|---|
| Vérifier les versions de Kubernetes et kubectl | Responsable plateforme : Alex Johnson | Avant chaque changement |
| Examiner les étiquettes, annotations et teintes actuelles | Ingénieur DevOps : Sam Lee | Avant chaque changement |
| Définir les changements souhaités dans les manifestes ou scripts | Propriétaire de l'application : Priya Shah | Avant chaque changement |
Tester avec kubectl apply --dry-run=client et inspecter la sortie | Approbateur du pipeline CI/CD : Chris Chen | Avant chaque changement |
| Appliquer les changements de manière limitée (par exemple, un espace de noms) | Opérateur de déploiement : Dana White | Au moment de l'application |
Vérifier avec les commandes kubectl get et describe | Ingénieur QA : Jordan Patel | Après l'application |
| Vérifier la planification des pods et la santé de l'application | SRE de garde : Taylor Kim | Après l'application, et pendant les 24 heures suivantes |
| Documenter les changements et les étapes de restauration | Rédacteur technique : Morgan Davis | Après chaque changement |
| Surveiller tout comportement inattendu | Responsable observabilité : Riley Garcia | En continu pendant 48 heures |
| Revoir et mettre à jour la liste de contrôle elle-même | Responsable plateforme : Alex Johnson | Mensuellement |
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.