Знакомство с Kubernetes. Часть 12: Аннотации

Для добавления произвольных, неидентифицирующиих метаданных к создаваемым в кластере Kubernetes объектам можно использовать аннотации. Клиенты (в том числе инструменты и библиотеки) могут получать и использовать эти данные. Давайте разберемся!

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

Как и метки, аннотации представляют собой пары ключ/значение, и в общем виде могут выглядеть так:

"metadata": {
  "annotations": {
    "key1" : "value1",
    "key2" : "value2"
  }
}

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

Несколько примеров информации, которую можно (а иногда и нужно) добавлять в аннотации:

• поля, создаваемые декларативной конфигурацией (declarative configuration layer). Такие поля, прикрепленные в виде аннотаций, позволяют отличать их от значений по умолчанию или от автоматически генерируемых полей;
• версия билда, релиза, информация о docker-образе (временные метки, имя ветви из репозитория, номер PR и т.д.);
• информация о логировании, мониторинге, аналитике и пр.;
• информация об используемых библиотеках или утилитах, которые могут использоваться в целях отладки;
• информация о пользователе или системе (к примеру, URL-адреса связанных объектов или список зависимых микросервисов);
• метаданные для ускоренного отката на предыдущую работоспособную версию приложения (например, конфиги);
• контактные данные ответственных за данный объект лиц.

Стоит отметить, что при создании объектов в кластере Kubernetes с помощью команды kubectl apply -а <имя_файла>, в аннотации к объекту автоматически создастся ключ kubectl.kubernetes.io/last-applied-configuration:, содержащий, как можно догадаться, последнюю успешно примененную конфигурацию (в json-формате).

Например, если сервис описан в файле auth0-svc.yaml следующим образом:

apiVersion: v1
kind: Service
metadata:
  name: auth0-proxy
spec:
  clusterIP: None
  ports:
  - port: 8080
  selector:
    app: auth0-proxy

и создаем его командой:

kubectl apply -f auth0-svc.yaml

то с помощью команды:

kubectl get svc auth0-proxy -o yaml --export=true

можно получить не только описание сервиса (в том числе, с полями по умолчанию), но и последнюю удачно развернутую версию из аннотации:

apiVersion: v1
kind: Service
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"v1","kind":"Service","metadata":{"annotations":{},"name":"auth0-proxy","namespace":"default"},"spec":{"clusterIP":"None","ports":[{"port":8080}],"selector":{"app":"auth0-proxy"}}}      
  creationTimestamp: null
  name: auth0-proxy
  selfLink: /api/v1/namespaces/default/services/auth0-proxy
spec:
  clusterIP: None
  ports:
  - port: 8080
    protocol: TCP
    targetPort: 8080
  selector:
    app: auth0-proxy
  sessionAffinity: None
  type: ClusterIP
status:
  loadBalancer: {}