K8s Q A Annotations

Аннотации

Для добавления произвольных, неидентифицирующиих метаданных к создаваемым в кластере 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: {}