3 min de lecture
Labels et selectors Kubernetes : le guide de terrain
Les labels et selectors Kubernetes au quotidien : commandes essentielles, intégration dans les Services, et pièges classiques à éviter.
Sommaire
Les labels sont une des mécaniques les plus fondamentales de Kubernetes, et pourtant une source fréquente de confusion et d'erreurs en production. Ce guide couvre les usages du quotidien.
Qu'est-ce qu'un label ?#
Un label est une paire clé-valeur attachée à n'importe quelle ressource Kubernetes. Il n'a pas de signification intrinsèque pour le cluster — c'est vous qui lui donnez du sens.
metadata:
labels:
app: api
version: v2
environment: production
team: backend
Les labels servent à deux choses : identifier les ressources (pour les retrouver, les filtrer) et sélectionner les ressources (pour les cibler depuis d'autres objets comme les Services ou les Deployments).
Commandes du quotidien#
Filtrer avec -l#
# Lister tous les pods de l'app "api"
kubectl get pods -l app=api
# Lister les pods "api" en version v2
kubectl get pods -l app=api,version=v2
# Tous les pods qui ont un label "team" (quelle que soit la valeur)
kubectl get pods -l team
# Tous les pods dont "environment" est "production" ou "staging"
kubectl get pods -l 'environment in (production, staging)'
# Tous les pods qui n'ont pas le label "canary"
kubectl get pods -l '!canary'
La syntaxe -l accepte deux formats : equality-based (key=value, key!=value) et set-based (key in (v1,v2), !key).
Afficher les labels#
# Voir les labels de tous les pods
kubectl get pods --show-labels
# Ajouter une colonne pour des labels spécifiques
kubectl get pods -L app,version
Ajouter et supprimer des labels#
# Ajouter un label à un pod existant
kubectl label pod my-pod env=debug
# Modifier un label existant (--overwrite obligatoire)
kubectl label pod my-pod env=staging --overwrite
# Supprimer un label (tiret final)
kubectl label pod my-pod env-
Les selectors dans les Services#
C'est là que les labels deviennent critiques. Un Service Kubernetes utilise un selector pour déterminer quels pods reçoivent le trafic :
apiVersion: v1
kind: Service
metadata:
name: api-service
spec:
selector:
app: api
version: v2
ports:
- port: 80
targetPort: 8080
Ce Service envoie le trafic uniquement aux pods qui ont à la fois app=api et version=v2. C'est un ET logique — tous les selectors doivent correspondre.
Piège classique n°1 : selector trop large#
Si deux Deployments partagent le même label app=api sans différenciateur supplémentaire, un Service qui sélectionne app=api routera vers les pods des deux Deployments. Toujours ajouter un label suffisamment discriminant (version, component, tier).
Piège classique n°2 : mismatch entre Deployment et Service#
Un Service qui n'envoie pas de trafic est souvent dû à un mismatch de labels. Vérifier avec :
kubectl describe service api-service
La ligne Endpoints liste les IPs des pods sélectionnés. Si elle est vide (<none>), le selector ne matche rien.
Le selector dans les Deployments#
Un Deployment a deux endroits distincts pour les labels :
spec:
selector:
matchLabels:
app: api # Selector du Deployment — IMMUABLE après création
template:
metadata:
labels:
app: api # Labels appliqués aux pods créés
version: v2 # Peut évoluer, ex: v3 pour un rolling update
Le spec.selector d'un Deployment est immuable après création. Le modifier nécessite de supprimer et recréer le Deployment. Le spec.template.metadata.labels peut évoluer, mais le selector doit toujours correspondre au sous-ensemble des labels des pods.
La différence avec les annotations#
Les annotations stockent des métadonnées non-sélectables. Elles ne peuvent pas être utilisées dans un selector. Elles servent à stocker des informations supplémentaires : URL de documentation, identifiant de build, timestamps.
metadata:
labels:
app: api # Sélectionnable
annotations:
build/git-sha: "abc123def456" # Non-sélectionnable
docs/runbook: "https://..."
Règle simple : si vous avez besoin de filtrer ou sélectionner via cet attribut → label. Sinon → annotation.
Conventions recommandées#
Les labels recommandés par Kubernetes donnent une base cohérente interopérable avec Helm, ArgoCD et les outils d'observabilité :
| Label | Exemple | Usage |
|---|---|---|
app.kubernetes.io/name | api | Nom de l'application |
app.kubernetes.io/version | v2.1.0 | Version déployée |
app.kubernetes.io/component | frontend | Composant dans l'architecture |
app.kubernetes.io/part-of | shop | Application parente |
app.kubernetes.io/managed-by | helm | Outil de gestion |
Ces labels standardisés améliorent la lisibilité dans les dashboards (Grafana, Lens, k9s) et facilitent les sélections cross-namespaces.
Selectors dans les NetworkPolicies#
Les labels ne servent pas qu'aux Services. Les NetworkPolicies Kubernetes utilisent également des selectors pour définir les règles de trafic entre pods :
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-api-to-db
spec:
podSelector:
matchLabels:
app: db # S'applique aux pods "db"
ingress:
- from:
- podSelector:
matchLabels:
app: api # Autorise uniquement les pods "api"
Une stratégie de labels cohérente dès le départ évite de devoir refactorer les NetworkPolicies plus tard.