Аннотации в Kubernetes (K8s) — это метаданные с дополнительной информацией, связанной с ресурсом или объектом. В этой статье разберемся, что они из себя представляют, для чего служат и чем отличаются от меток.

Аннотации состоят из пар ключ-значение. Каждая пара используется для описания метаданных ресурса или предоставления дополнительной информации. Например, его можно использовать для записи создателя ресурса, версии, истории изменений, отношения к определенному компоненту и т. д.

Когда использовать аннотации?

Аннотации можно применять к различным ресурсам Kubernetes. Обычно они используются для модулей, служб, развертывания и входов.

Пользователи кластеров Kubernetes могут сами определять, как использовать аннотации и как настраивать их для конкретных случаев или потребностей.

Это пример YAML аннотаций для модулей.

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    key1: value1
    key2: value2
spec:
  # The spec fields of the pod

Аннотации используются в качестве заметок, тегов или метаданных в Kubernetes. Их можно использовать, чтобы оставить дополнительную информацию о деталях ресурсов. Они могут быть полезны для интеграции с внешними системами и инструментами, которые управляют или отслеживают ресурсы Kubernetes.

Kubernetes предоставляет различные API и механизмы для интеграции со многими инструментами разработчика и оператора: системами мониторинга, системами ведения журналов, конвейерами CI/CD и многим другим. Аннотации могут быть полезны для интеграции с ними.


Реальные примеры

Рассмотрим следующий сценарий: разработчик проделал какую-то работу и внес функциональные изменения в определенный модуль. Он хочет чтобы автоматически запускались тесты и развертывания через конвейер CI/CD.

В то же время разработчик может внести изменения во внешнюю систему CI/CD, обновив аннотацию соответствующего модуля. Системы CI/CD проверят аннотации и запустят процессы автоматического тестирования и развертывания.

Другой пример — интеграция с системами мониторинга. Вы можете использовать аннотации для настройки уведомлений мониторинга для определенных ресурсов или отображать некоторые значения аннотаций на панели мониторинга.

Это позволяет разработчикам или операторам видеть дополнительную информацию о своих ресурсах Kubernetes и улучшать их взаимодействие с системой мониторинга. Таким образом, использование аннотаций может быть полезно в различных аспектах управления и эксплуатации, таких как автоматизация, мониторинг, ведение журналов и безопасность.


Давайте посмотрим на пример yaml. Следующий код создает модуль с определенной аннотацией. Я использовал LKE (Linode Kubernetes Engine) для быстрой реализации.

apiVersion: v1
kind: Pod
metadata:
  name: annotations-demo
  annotations:
    imageregistry: "https://hub.docker.com/"
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

После создания модуля просмотрите информацию о модуле в формате yaml.

apiVersion: v1
kind: Pod
metadata:
  annotations:
    cni.projectcalico.org/containerID: 0ab80d898468c9cbc235c873eb05470c551666392f268a8add44844773b3bbd8
    cni.projectcalico.org/podIP: 10.2.1.11/32
    cni.projectcalico.org/podIPs: 10.2.1.11/32
    imageregistry: https://hub.docker.com/
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"v1","kind":"Pod","metadata":{"annotations":{"imageregistry":"https://hub.docker.com/"},"name":"annotations-demo","namespace":"default"},"spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx","ports":[{"containerPort":80}]}]}}
  creationTimestamp: "2023-05-21T00:48:19Z"
  name: annotations-demo

Аннотации, полученные в приведенном выше примере YAML, содержат следующие пары ключ-значение:

  1. cni.projectcalico.org/containerID — идентификатор контейнера для этого пода. Это значение можно использовать для идентификации контейнеров, управляемых сетевым подключаемым модулем Calico.

  2. cni.projectcalico.org/podIP — IP-адрес пода. Сетевой плагин Calico использует это значение для записи IP-адреса, назначенного модулю.

  3. cni.projectcalico.org/podIPs — IP-адрес соответствующего пода. Сетевой плагин Calico используется для записи IP-адресов, назначенных модулям.

  4. imageregistry — значение, добавленное вручную. Его можно использовать, чтобы указать, из какого реестра берутся образы, используемые этим модулем.

  5. kubectl.kubernetes.io/last-applied-configuration — значение для записи последней примененной конфигурации. Его можно использовать для отслеживания или отладки изменений конфигурации этого модуля.

Эти аннотации можно использовать в первую очередь для взаимодействия с сетевыми плагинами Calico и различными функциями кластера Kubernetes. Например, Calico используется для предоставления сетевых политик, функций безопасности, управления IP-адресами и т. д., а соответствующая информация может храниться в аннотациях. Кроме того, такая информация, как URL-адреса реестра изображений или история изменений конфигурации, может быть включена в аннотации для использования при управлении кластером и отладке.


В дополнение к ключу imageregistry, определенному в YAML, поле аннотаций уже содержит другие значения.

Как правило, аннотации не создаются автоматически при создании пода в Kubernetes. Аннотации — это метаданные, которые вы определяете и добавляете сами. Поэтому при создании нового пода поле «Аннотации» по умолчанию пусто.

Однако в определенных ситуациях аннотации также могут создаваться автоматически. Например, некоторые инструменты управления или контроллеры Kubernetes сами генерируют и используют аннотации. Эти инструменты или контроллеры могут использовать аннотации для облегчения управления модулями или для поддержки определенных задач.

Например, Horizontal Pod Autoscaler (HPA) Kubernetes работает с Metrics Server для автоматического масштабирования количества управляемых модулей. HPA может использовать аннотации для отслеживания информации о скоординированных модулях. HPA обновляет поле аннотаций модуля, чтобы сохранить такую ​​информацию, как текущее состояние масштабирования, количество настроенных модулей и т. д.

Другой пример — механизм управления событиями Kubernetes. События, происходящие в кластере Kubernetes, используются для отслеживания изменений состояния или проблем в кластере. Информация о событии может быть автоматически записана в поле «Аннотации» каждого ресурса. Благодаря этому инструменты управления событиями или системы мониторинга могут проверять и анализировать записи о событиях ресурсов.

В чем сходство и различие между аннотациями и метками?

Аннотации и метки — это пары «ключ-значение», используемые для прикрепления метаданных к объектам Kubernetes, таким как модули, службы и развертывания. Между ними есть некоторые различия.

Метки в основном используются для идентификации и группировки ресурсов в Kubernetes, а аннотации используются для прикрепления произвольных метаданных для внешних инструментов и систем, которые можно использовать. Метки имеют семантическое значение и используются самим Kubernetes, тогда как аннотации рассматриваются как непрозрачные строки и не влияют на внутренние операции Kubernetes.

Метки предназначены для Kubernetes, а аннотации — для людей!


Узнать больше про работу Kubernetes, можно в Слёрме на курсе «Kubernetes Мега». Это продвинутый курс для тех, кто уже знает этот инструмент, но хочет заглянуть под капот, а также повысить стабильность и отказоустойчивость инфраструктуры.

Курс ? «Kubernetes Мега» на нашем сайте.