lumikha

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.

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é :

LabelExempleUsage
app.kubernetes.io/nameapiNom de l'application
app.kubernetes.io/versionv2.1.0Version déployée
app.kubernetes.io/componentfrontendComposant dans l'architecture
app.kubernetes.io/part-ofshopApplication parente
app.kubernetes.io/managed-byhelmOutil 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.

← Tous les articles