Les Annotations : Attacher des métadonnées non identifiantes

Au-delà de l'identification : enrichir les objets Kubernetes

Nous avons vu comment les Labels et Selectors sont essentiels pour organiser et sélectionner les objets Kubernetes. Cependant, nous avons souvent besoin d'attacher d'autres types d'informations à nos objets : des descriptions, des informations de build, des instructions pour des outils externes, des coordonnées de contact, etc. Ces informations ne sont pas destinées à être utilisées pour identifier ou sélectionner des objets, mais plutôt à fournir un contexte supplémentaire pour les humains ou d'autres systèmes.

C'est là qu'interviennent les Annotations. Tout comme les Labels, les Annotations sont des paires clé-valeur définies dans la section `metadata` d'un objet Kubernetes. Cependant, leur objectif est différent : elles permettent d'attacher des métadonnées arbitraires et non identifiantes aux objets.

Comprendre la distinction entre Labels et Annotations est crucial pour utiliser correctement les métadonnées dans Kubernetes. Les Annotations offrent une flexibilité beaucoup plus grande pour stocker des informations diverses qui ne rentrent pas dans le cadre strict de l'identification et de la sélection.

Rôle et cas d'usage des Annotations

Les Annotations servent à stocker des informations qui ne sont pas utilisées par Kubernetes lui-même pour identifier ou sélectionner des objets, mais qui peuvent être utiles pour :

• Informations pour les outils et bibliothèques : De nombreux outils de l'écosystème Kubernetes (contrôleurs Ingress, outils de monitoring, gestionnaires de certificats comme cert-manager, outils CI/CD) utilisent les Annotations pour obtenir des configurations spécifiques ou pour stocker leur propre état. Par exemple, un contrôleur Ingress peut lire des annotations sur un objet Ingress pour savoir comment configurer des redirections spécifiques ou des limites de taux.
• Métadonnées de build, de release ou d'image : Informations comme le timestamp du build, l'ID de commit Git, le numéro de version de l'image, l'URL du registre Docker.
• Coordonnées et informations de propriété : Nom de l'équipe responsable, adresse email de contact, lien vers un outil de gestion de projet.
• Instructions opérationnelles ou descriptions : Ajouter une description lisible par l'homme sur l'objectif d'un objet, des pointeurs vers de la documentation, ou des instructions pour le débogage.
• Politiques ou informations spécifiques à une logique métier : Par exemple, marquer un objet comme nécessitant une revue de sécurité particulière.

En bref, si une information n'est pas destinée à être utilisée dans un `selector`, elle devrait probablement être une Annotation plutôt qu'un Label.

Syntaxe et caractéristiques

Les Annotations sont définies dans la section `metadata.annotations` d'un manifeste YAML, de manière similaire aux Labels :

apiVersion: v1
kind: Pod
metadata:
  name: mon-pod-avec-annotations
  labels:
    app: backend
  annotations:
    imageregistry: "https://hub.docker.com/"
    prometheus.io/scrape: "true"
    prometheus.io/port: "9102"
    description: "Pod exemple avec un serveur web simple et des annotations diverses."
    contact: "admin@example.com"
    git-commit: "a1b2c3d4e5f6"

Caractéristiques clés :

• Format Clé-Valeur : Comme les Labels, elles fonctionnent par paires clé-valeur.
• Clés : Les clés suivent les mêmes règles de nommage que les clés de Labels (préfixe DNS optionnel / nom). Les mêmes préfixes réservés (`kubernetes.io/`, `k8s.io/`) s'appliquent. Il est courant d'utiliser des préfixes de domaine inversé (comme `prometheus.io/`) pour éviter les collisions entre outils.
• Valeurs : Contrairement aux Labels, les valeurs des Annotations peuvent être arbitrairement grandes et complexes. Elles ne sont pas limitées à 63 caractères et peuvent contenir n'importe quelle chaîne de caractères (souvent du JSON ou d'autres formats structurés encodés en chaîne, bien que ce ne soit pas toujours recommandé pour la lisibilité).
• Non indexées : Kubernetes n'indexe pas les Annotations. Par conséquent, vous ne pouvez pas utiliser de Selectors pour filtrer des objets en fonction de leurs Annotations. La recherche basée sur les annotations est beaucoup moins efficace que celle basée sur les labels.

Labels vs Annotations : le résumé définitif

Pour résumer clairement la différence :

Utilisez les Labels lorsque vous avez besoin de regrouper des objets pour que Kubernetes ou vous-même puissiez les sélectionner efficacement. Utilisez les Annotations pour tout le reste : informations descriptives, configuration d'outils, métadonnées de contexte.

Gérer les Annotations avec `kubectl`

De manière similaire aux labels, `kubectl` fournit une sous-commande pour gérer les annotations : `kubectl annotate`.

• Ajouter ou mettre à jour une annotation :
  - `kubectl annotate pods mon-pod description="Ceci est mon pod de test"` : Ajoute l'annotation `description`.
  - `kubectl annotate pods mon-pod description="Nouvelle description" --overwrite` : Met à jour une annotation existante (requiert `--overwrite`).
• Afficher les annotations : Les annotations ne sont généralement pas affichées par défaut avec `kubectl get`. Vous devez utiliser `-o yaml` ou `-o json` pour voir la section `metadata.annotations`.
  - `kubectl get pod mon-pod -o yaml`
• Supprimer une annotation :
  - `kubectl annotate pods mon-pod description-` : Supprime l'annotation avec la clé `description` (notez le `-` final).

Il n'existe pas de flag `-l` ou `--selector` pour filtrer directement sur les annotations avec `kubectl get`. Si vous avez besoin de trouver des objets basés sur une annotation, vous devrez généralement récupérer tous les objets concernés (ou un sous-ensemble basé sur des labels) et filtrer la sortie côté client (par exemple, en utilisant `grep` ou `jq` sur la sortie JSON/YAML).

Conclusion : l'espace libre pour les métadonnées

Les Annotations complètent les Labels en fournissant un espace flexible pour associer des informations contextuelles et non structurées aux objets Kubernetes. Elles sont essentielles pour l'intégration avec l'écosystème d'outils autour de Kubernetes et pour ajouter des informations utiles aux humains qui interagissent avec le cluster.

En utilisant judicieusement les Labels pour l'identification et la sélection, et les Annotations pour les métadonnées descriptives ou spécifiques aux outils, vous maintenez une organisation claire et efficace de vos ressources Kubernetes. Vous disposez maintenant d'une compréhension complète des mécanismes de métadonnées fondamentaux de Kubernetes.