kubectl label et annotate : organiser et documenter vos ressources Kubernetes

Labels et annotations sont les deux systèmes de métadonnées de Kubernetes, mais ils ne servent pas du tout à la même chose. Les labels sont des paires clé-valeur que Kubernetes utilise pour sélectionner et router : un Service trouve ses pods via un label selector, un Deployment gère ses réplicas par labels. Les annotations sont du texte libre pour documenter et outiller : référence d'incident, config Ingress, scrape Prometheus. Ce guide vous montre comment les gérer efficacement avec kubectl label et kubectl annotate.

Ce que vous allez apprendre

La différence entre labels et annotations, et quand utiliser l'un ou l'autre
Ajouter, modifier et supprimer des labels et annotations sur n'importe quelle ressource
Filtrer des ressources avec les label selectors (-l)
Adopter les labels recommandés par Kubernetes (app.kubernetes.io/*)
Exploiter les annotations pour le tooling (Ingress, Prometheus, Cert-Manager…)
Appliquer en masse des métadonnées sur plusieurs ressources

Label ou annotation ? Le choix rapide

Avant de taguer quoi que ce soit, posez-vous cette question : Kubernetes ou un autre outil devra-t-il sélectionner des ressources avec cette information ?

Critère	Label	Annotation
But	Identifier, sélectionner, grouper	Documenter, configurer des outils
Utilisé par les selectors (`-l`)	✅ Oui	❌ Non
Utilisé par les Services/Deployments	✅ Oui (routing, réplicas)	❌ Non
Longueur valeur	63 caractères max	Pas de limite pratique
Caractères autorisés	Alphanumériques, `-`, `_`, `.`	Texte libre
Exemple typique	`env=prod`, `app=api`, `tier=backend`	`owner=equipe-platform`, `prometheus.io/scrape=true`

kubectl label : organiser et sélectionner

Les labels sont le mécanisme fondamental de Kubernetes pour lier les ressources entre elles. Un Service trouve ses pods par label selector. Un Deployment identifie ses réplicas par labels. Sans labels, Kubernetes ne peut pas fonctionner.

Syntaxe

La commande accepte n'importe quel type de ressource (pod, deploy, node, namespace) et autant de paires clé-valeur que vous voulez sur une seule ligne.

kubectl label <type> <nom> <clé>=<valeur> [options]

Recettes essentielles

Les quatre opérations ci-dessous couvrent la quasi-totalité des besoins : ajouter, modifier, supprimer et appliquer en masse. Chacune renvoie une ligne de confirmation qui nomme la ressource touchée, ce qui vous permet de vérifier que la commande a bien visé le bon objet avant d'aller plus loin.

Ajouter un label

Sans option particulière, kubectl label n'écrit que si la clé est absente de la ressource.

kubectl label pod api-server-7d4b8c env=production

pod/api-server-7d4b8c labeled

Modifier un label existant

Par défaut, kubectl refuse d'écraser un label existant. Ajoutez --overwrite :

kubectl label pod api-server-7d4b8c env=staging --overwrite

Supprimer un label

Ajoutez un - (tiret) après le nom de la clé :

kubectl label pod api-server-7d4b8c env-

pod/api-server-7d4b8c unlabeled

Labelliser plusieurs ressources d'un coup

Trois façons de désigner une cible multiple : plusieurs noms à la suite, le drapeau --all qui prend tout le namespace, ou un sélecteur -l qui ne retient que les ressources déjà porteuses d'un label donné.

# Par nom
kubectl label pods api-server-7d4b8c worker-9f2a1e tier=backend

# Tous les pods d'un namespace
kubectl label pods --all env=staging -n dev

# Par sélecteur (tous les pods de l'app api)
kubectl label pods -l app=api version=v2.1 -n prod

Filtrer avec les label selectors (-l)

Les label selectors sont l'un des outils les plus puissants de kubectl. Ils fonctionnent partout : get, delete, logs, exec…

# Égalité
kubectl get pods -l env=production

# Inégalité
kubectl get pods -l env!=staging

# Appartenance (in)
kubectl get pods -l 'env in (production, staging)'

# Exclusion (notin)
kubectl get pods -l 'env notin (dev, test)'

# Existence (le label existe, quelle que soit la valeur)
kubectl get pods -l env

# Non-existence
kubectl get pods -l '!env'

# Combinaison (ET logique : toutes les conditions doivent être vraies)
kubectl get pods -l app=api,env=production,tier=backend

Ajoutez --show-labels pour voir les labels de chaque ressource :

kubectl get pods -n prod --show-labels

Ou affichez un label spécifique en colonne :

kubectl get pods -n prod -L env -L tier

Labels recommandés par Kubernetes

Kubernetes définit un ensemble de labels standardisés sous le préfixe app.kubernetes.io/. Les adopter garantit la compatibilité avec les outils de l'écosystème (Helm, ArgoCD, Lens, Prometheus…).

Label	Rôle	Exemple
`app.kubernetes.io/name`	Nom de l'application	`api-gateway`
`app.kubernetes.io/version`	Version de l'application	`2.4.1`
`app.kubernetes.io/component`	Composant dans l'architecture	`frontend`, `backend`, `database`
`app.kubernetes.io/part-of`	Application parente	`boutique-en-ligne`
`app.kubernetes.io/managed-by`	Outil de déploiement	`helm`, `argocd`, `kubectl`
`app.kubernetes.io/instance`	Instance unique	`api-gateway-prod`

Exemple concret, un Deployment avec labels recommandés :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-gateway
  labels:
    app.kubernetes.io/name: api-gateway
    app.kubernetes.io/version: "2.4.1"
    app.kubernetes.io/component: backend
    app.kubernetes.io/part-of: boutique-en-ligne
    app.kubernetes.io/managed-by: helm

Contraintes de syntaxe des labels

Les labels ont des règles strictes, les dépasser provoque une erreur :

Contrainte	Règle
Clé (sans préfixe)	1-63 caractères, alphanumérique, `-`, `_`, `.`
Préfixe (optionnel)	Sous-domaine DNS, max 253 caractères, séparé par `/`
Valeur	0-63 caractères, alphanumérique, `-`, `_`, `.`, doit commencer et finir par un alphanumérique

# ✅ Valide
kubectl label pod mon-pod app.kubernetes.io/name=api-gateway

# ❌ Invalide : valeur trop longue ou caractères spéciaux
kubectl label pod mon-pod desc="Mon application de production avec beaucoup de détails"
# → error: invalid label value

kubectl annotate : documenter et outiller

Les annotations stockent des informations textuelles libres sur une ressource. Kubernetes ne les utilise pas pour la sélection, mais de nombreux outils s'en servent pour leur configuration.

Syntaxe

La syntaxe est la copie de celle de kubectl label, à une nuance près : la valeur peut contenir des espaces, des accents et de la ponctuation, à condition de la placer entre guillemets pour le shell.

kubectl annotate <type> <nom> <clé>=<valeur> [options]

Recettes essentielles

Les mêmes quatre gestes qu'avec les labels, avec les mêmes drapeaux : --overwrite pour remplacer, le tiret suffixe pour supprimer. La différence apparaît à la lecture : les annotations n'apparaissent pas dans kubectl get, il faut aller les chercher avec describe ou jsonpath.

Ajouter une annotation

Une adresse de contact est le cas le plus courant : elle reste attachée aux métadonnées de l'objet et s'affiche dans kubectl describe.

kubectl annotate pod api-server-7d4b8c owner="equipe-platform@example.com"

pod/api-server-7d4b8c annotated

Modifier une annotation existante

Comme pour les labels, l'écrasement d'une clé déjà présente échoue tant que vous n'ajoutez pas --overwrite.

kubectl annotate pod api-server-7d4b8c owner="equipe-sre@example.com" --overwrite

Supprimer une annotation

Le tiret suffixe derrière la clé retire l'annotation ; l'opération est immédiate et sans confirmation.

kubectl annotate pod api-server-7d4b8c owner-

Annoter plusieurs ressources

Le drapeau --all combiné à -n couvre tout un namespace en une commande, ce qui est pratique pour poser un motif de changement commun sur une vague de déploiements.

# Par nom
kubectl annotate pods api-server-7d4b8c worker-9f2a1e support-team="ops@example.com"

# Tous les deployments d'un namespace
kubectl annotate deploy --all -n prod change-cause="Mise à jour sécurité 2026-02-27"

Lire les annotations d'une ressource

kubectl get n'affiche pas les annotations, il n'existe pas d'équivalent de --show-labels. Il faut passer par jsonpath, un langage d'extraction intégré à kubectl qui pioche un champ précis dans l'objet JSON renvoyé par l'API.

# Toutes les annotations
kubectl get pod api-server-7d4b8c -o jsonpath='{.metadata.annotations}' | python3 -m json.tool

# Une annotation spécifique
kubectl get pod api-server-7d4b8c -o jsonpath='{.metadata.annotations.owner}'

Annotations utilisées par l'écosystème Kubernetes

Contrairement aux labels que vous définissez librement, certaines annotations ont un sens particulier pour des composants Kubernetes ou des outils tiers :

Annotation	Outil	Rôle
`kubernetes.io/change-cause`	kubectl rollout	Motif du changement affiché dans `rollout history`
`nginx.ingress.kubernetes.io/rewrite-target`	Ingress NGINX	Réécriture d'URL
`cert-manager.io/cluster-issuer`	Cert-Manager	Émetteur de certificat TLS
`prometheus.io/scrape`	Prometheus	Active le scraping de métriques
`prometheus.io/port`	Prometheus	Port à scraper
`argocd.argoproj.io/sync-wave`	ArgoCD	Ordre de synchronisation

Tracer les changements avec change-cause

L'annotation kubernetes.io/change-cause permet de documenter pourquoi un Deployment a été modifié. Elle apparaît dans kubectl rollout history :

Annotez le Deployment avec la raison du changement

kubectl annotate deploy api-gateway -n prod \
  kubernetes.io/change-cause="Mise à jour nginx 1.27, correctif CVE-2026-1234"

Vérifiez dans l'historique

kubectl rollout history deploy/api-gateway -n prod

REVISION  CHANGE-CAUSE
1         Déploiement initial
2         Mise à jour nginx 1.27, correctif CVE-2026-1234

Opérations en masse et cas d'usage prod

En production, les métadonnées se posent rarement une ressource à la fois. Vous héritez d'un namespace où la moitié des pods n'a pas de label env, ou vous devez renommer une clé sur toute une application. Les recettes ci-dessous combinent kubectl get et kubectl label via un pipe, et s'appliquent immédiatement au cluster. Ajoutez --dry-run=server à la commande de labellisation pour voir le résultat sans rien écrire dans etcd, la base de données du cluster.

Labelliser tous les pods non labellisés

Le sélecteur -l '!env' isole les ressources dépourvues de la clé, et xargs rejoue la commande de labellisation sur chaque nom retourné.

# Trouver les pods sans label env
kubectl get pods -n prod -l '!env' --no-headers -o custom-columns=":metadata.name" | \
  xargs -I{} kubectl label pod {} env=production -n prod

Supprimer un label de toutes les ressources

L'opération est irréversible : une fois la clé retirée, sa valeur n'est nulle part, et tout Service dont le selector s'appuyait dessus perd instantanément ses endpoints.

kubectl label pods --all -n dev legacy-

Migrer un label (renommer)

Kubernetes ne supporte pas le renommage direct. Il faut copier puis supprimer :

# Copier la valeur de l'ancien label vers le nouveau
for pod in $(kubectl get pods -n prod -l app=api -o name); do
  val=$(kubectl get "$pod" -n prod -o jsonpath='{.metadata.labels.app}')
  kubectl label "$pod" -n prod "app.kubernetes.io/name=$val"
done

# Supprimer l'ancien label
kubectl label pods -l app=api -n prod app-

Annotations d'incident (traçabilité prod)

En cas d'incident, annotez les ressources modifiées pour la post-mortem :

kubectl annotate deploy api-gateway -n prod \
  incident-ref="INC-2026-0142" \
  incident-action="Rollback image vers nginx:1.26" \
  incident-by="alice@example.com" \
  incident-date="2026-02-27T14:30:00Z"

Bonnes pratiques

Un cluster reste lisible tant que les métadonnées suivent une convention écrite. Sans cadre, chaque équipe invente son vocabulaire (env, environment, stage) et les sélecteurs cessent de fonctionner d'un namespace à l'autre. Les trois règles qui suivent tiennent en une page et suffisent à éviter la dérive.

Convention de nommage des labels

Adoptez une convention dès le départ et documentez-la. Voici un exemple :

Label	Valeurs possibles	Qui le pose
`env`	`dev`, `staging`, `prod`	CI/CD
`tier`	`frontend`, `backend`, `database`, `cache`	Manifest
`app.kubernetes.io/name`	Nom de l'application	Helm / manifest
`app.kubernetes.io/version`	Semver	CI/CD
`team`	`platform`, `sre`, `produit`	Manifest

Séparer labels et annotations

En cas de doute, demandez-vous si un contrôleur doit un jour faire une requête sur cette information.

Label = ce qui sert à sélectionner (Services, Deployments, NetworkPolicies, monitoring)
Annotation = ce qui sert à documenter ou configurer un outil (Ingress, Cert-Manager, Prometheus)
Ne mettez jamais d'information longue ou changeante dans un label (URL, description, timestamp)

Ne pas surcharger les labels

Plus il y a de labels, plus les selectors deviennent complexes. 5 à 8 labels par ressource est un maximum raisonnable. Au-delà, regroupez via des annotations ou des ConfigMaps de documentation.

Dépannage

Les erreurs de labels et d'annotations se ressemblent toutes : kubectl refuse d'écrire, ou bien il écrit mais rien ne se passe côté cluster. Le tableau associe chaque message d'erreur exact à sa cause. Retenez surtout les deux dernières lignes : quand une métadonnée disparaît sans explication, le coupable est presque toujours un outil GitOps qui resynchronise l'état depuis Git.

Symptôme	Cause probable	Solution
`error: invalid label value`	Valeur > 63 caractères ou caractères spéciaux	Raccourcissez ou utilisez une annotation à la place
`error: 'X' already has a value`	Le label existe déjà sur la ressource	Ajoutez `--overwrite`
`error: 'X' already has a value` (annotate)	L'annotation existe déjà	Ajoutez `--overwrite`
`-l` ne retourne rien	Mauvais namespace ou label inexistant	Vérifiez avec `kubectl get <type> --show-labels -n <ns>`
Service ne route pas vers les pods	Labels du Service selector ≠ labels des pods	Comparez `kubectl get svc <nom> -o jsonpath='{.spec.selector}'` avec les labels des pods
`invalid label key`	Préfixe DNS invalide ou clé trop longue	Vérifiez : clé max 63 chars, préfixe max 253 chars, format DNS
Annotations perdues après `replace`	`kubectl replace` remplace l'objet entier	Utilisez `kubectl annotate` ou `kubectl apply -f` à la place
Labels supprimés par ArgoCD/Flux	L'outil GitOps resynchronise depuis Git	Ajoutez les labels dans le manifest Git, pas via `kubectl label`

À retenir

Labels = sélection et routage (Services, Deployments, NetworkPolicies les utilisent pour trouver les bons pods).
Annotations = documentation et configuration d'outils (Ingress, Prometheus, Cert-Manager, traçabilité).
La syntaxe est identique : kubectl label et kubectl annotate avec --overwrite pour modifier, - pour supprimer.
Adoptez les labels app.kubernetes.io/*, ils sont le standard de l'écosystème (Helm, ArgoCD, Lens).
Les labels ont des contraintes strictes (63 chars, alphanumériques), si ça ne rentre pas, c'est probablement une annotation.
Les label selectors (-l) supportent l'égalité, l'inégalité, in, notin et le test d'existence.
En prod, documentez vos conventions de labels dans un document partagé par toutes les équipes.

Prochaines étapes

Créer et déployer avec create et apply Définir des labels et annotations dès la création de vos ressources.

Modifier avec edit, patch et replace Modifier les labels et annotations existantes via patch ciblé.

Diagnostiquer avec get, describe et logs Filtrer vos commandes de diagnostic avec les label selectors.

Scale, autoscale et rollout Utiliser rollout history avec change-cause pour tracer les mises à jour.

Explorer l'API Kubernetes Découvrir les champs metadata.labels et metadata.annotations avec kubectl explain.