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

Glissez pour voir

Règle simple

Si Kubernetes ou un outil a besoin de filtrer avec cette information → label. Si c’est une information pour les humains ou la configuration d’un outil externe → annotation.

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

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

Recettes essentielles

Ajouter un label

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

# 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

Afficher les labels dans la sortie

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

Glissez pour voir

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

Glissez pour voir

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

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

Recettes essentielles

Ajouter une annotation

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

pod/api-server-7d4b8c annotated

Modifier une annotation existante

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

Supprimer une annotation

kubectl annotate pod api-server-7d4b8c owner-

Annoter plusieurs ressources

# 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

# 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

Glissez pour voir

Annotations et taille

Les annotations n’ont pas de limite de longueur stricte comme les labels, mais l’ensemble des métadonnées d’un objet (labels + annotations) est stocké dans etcd. Évitez d’y stocker des blobs volumineux (logs, fichiers encodés) — etcd a une taille max par objet de 1,5 Mo.

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 :

1. 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"

2. 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

Labelliser tous les pods non labellisés

# 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

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

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

Glissez pour voir

Séparer labels et annotations

• 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

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

Glissez pour voir

À 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.

×

📖 Voir la documentation →