Просмотр кода страницы Обогащение метаданных всей телеметрии, поступающей из Kubernetes

= Обогащение метаданных всей телеметрии, поступающей из Kubernetes =

В этой статье описываются различные способы обогащения сигналов телеметрии '''Kubernetes''' метаданными в операторе Ключ-АСТРОМ: аннотации пространств имен и подов, переменные среды '''OpenTelemetry''' и атрибуты ресурсов, определенные непосредственно в '''DynaKube'''.

== Предварительные требования ==
* Оператор Ключ-АСТРОМ установлен и запущен в вашем кластере '''Kubernetes'''.
* В ваш кластер добавлен корректный '''DynaKube'''.
* Функция обогащения метаданных включена.

== Варианты использования ==
* Дополните свои метрики, логи, данные трассировки, события и сущности дополнительной информацией, используя аннотации и метки пространств имен '''Kubernetes'''.
* Расширьте свои метрики, логи, данные трассировки, события и сущности, добавив дополнительную информацию с помощью переменных среды '''OpenTelemetry'''.
* Обогащенные данные могут использоваться для определения контроля доступа пользователей или для решения задач распределения затрат в системах управления данными.
* Обогащенные данные могут использоваться для маршрутизации трубопроводов, сегментации сегментов, сегментации и фильтрации.

== Контекст безопасности и распределение затрат ==
В Ключ-АСТРОМ можно настроить границы политик для более точных ограничений на уровне данных. По умолчанию можно использовать <code>k8s.namespace.name</code> и <code>k8s.cluster.name</code>, но иногда этого недостаточно, и требуется более точный способ настройки границ.

Возможно, вы уже определили такие границы самостоятельно и задали их в виде меток или аннотаций '''Kubernetes'''. Эта функция позволяет использовать их в качестве контекста безопасности в Ключ-АСТРОМ. Если вы еще этого не сделали, мы рекомендуем использовать имя кластера или пространства имен, либо настроить отдельную аннотацию для ваших рабочих нагрузок '''Kubernetes''', которая будет служить контекстом безопасности.

Аналогичным образом Ключ-АСТРОМ предлагает решение для распределения затрат в '''DPS'''. Возможно, у вас уже есть необходимые данные, такие как отдел и продукт, в существующих метках или аннотациях '''Kubernetes'''. Даже если нет, вам может быть очень удобно настроить распределение затрат в виде аннотации или метки '''Kubernetes''', что и рекомендует Ключ-АСТРОМ. Эта функция позволяет использовать эти метки и аннотации для решения задачи распределения затрат в '''DPS'''.

Поддерживаются следующие атрибуты:
* <code>dt.security_context</code>
* <code>dt.cost.costcenter</code>
* <code>dt.cost.product</code>

== Доменные теги ==
Для упрощения таких задач, как выбор сегментов, сегментация, фильтрация и маршрутизация проблем, Ключ-АСТРОМ позволяет обогащать данные телеметрии, используя существующие метки или аннотации пространства имен '''Kubernetes'''. Эти теги доступны в виде полей, специфичных для предметной области, например, <code>k8s.namespace.label.your_key</code> или <code>k8s.namespace.annotation.your_key</code>.

== Какие данные будут обогащены? ==
{| class="wikitable"
|-
! Данные !! Доменные теги !! Контекст безопасности !! Распределение затрат
|-
| метрики ЕдиногоАгента || ✓ || ✓ || ✓
|-
| Метрики JMX/PMI собираются через ЕдиныйАгент || ✓ || ✓ || ✓
|-
| Показатели обслуживания || ✓ || ✓ || ✓
|-
| метрики платформы '''Kubernetes''' || Запланировано || Запланировано || Запланировано
|-
| Данные, собранные '''OpenTelemetry Collector''' || ✓ || ✓ || ✓
|-
| Метрики, собранные '''OpenTelemetry Collector''' || ✓ || ✓ || ✓
|-
| Логи, собранные '''OpenTelemetry Collector''' || ✓ || ✓ || ✓
|-
| Логи, собранные модулем логов ЕдиногоАгента || ✓ || ✓ || ✓
|-
| Логи, собранные '''FluentBit''' || ✓ || ✓ || ✓
|-
| сущности '''Smartscape Kubernetes''' || ✓ || ✓ || ✓
|-
| События ЕдиногоАгента || ✓ || ✓ || ✓
|-
| События '''Kubernetes''' || ✓ || ✓ || ✓
|}

== Варианты обогащения ==
В зависимости от конкретного сценария использования поддерживаются следующие варианты обогащения данных:

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

Подсказка: Если вы настроите правила до развертывания '''Dynakube''', вам не нужно будет ждать 45 минут, пока правила распространятся.

# Перейдите в '''Kubernetes App''' > '''Пространства имен''' > Выберите свое пространство имен, чтобы просмотреть существующие метки пространства имен.
# Перейдите в '''Настройки''' > '''Облако и виртуализация''' > '''Обогащение телеметрии Kubernetes'''.
# Выберите '''Добавить правило'''.
# Выберите '''Annotation''' или '''Label''' в раскрывающемся списке '''Тип метаданных'''.
# В поле '''Источник''' введите ключ аннотации/метки пространства имен, следуя [https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set соглашениям Kubernetes]:
#* Чтобы использовать ключ аннотации или метки в качестве имени поля, включите параметр '''Обогащать телеметрию непосредственно меткой/аннотацией'''.
#* Для переназначения отключите функцию '''Обогащать телеметрию метками/аннотациями''' и выберите значение из раскрывающегося списка '''Цель'''.
# Выберите '''Сохранить изменения'''.

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

=== Настройка атрибутов ресурсов в DynaKube ===
Оператор Ключ-АСТРОМ версии 1.10.0+

Дополнительные атрибуты ресурсов можно определить непосредственно в '''DynaKube'''. Оператор Ключ-АСТРОМ распространяет их на все сигналы телеметрии без необходимости использования меток пространств имен или аннотаций подов.

=== Используйте специальные аннотации метаданных Ключ-АСТРОМ для модулей ===
Это автоматически работает для сценариев изменения кода ЕдиногоАгента и '''OpenTelemetry'''.

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

В отличие от подхода, основанного на настройках, добавленные вручную аннотации подов не обеспечивают полного обогащения. Они не будут обогащать метрики '''Kubernetes''', события '''Kubernetes''' или сущности. Для обогащения метрик ЕдиногоАгента и метрик сервисов этими атрибутами необходимо соблюдать соглашение <code>k8s.namespace.<label>/<annotation>.<key>: <value></code>.

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

На уровне пода вы можете создать следующие аннотации:
{| class="wikitable"
|<pre>
metadata:
  annotations:
    metadata.astromkey.com/dt.security_context: sre
    metadata.astromkey.com/dt.cost.costcenter: it_services
    metadata.astromkey.com/dt.cost.product: fin_app
    metadata.astromkey.com/k8s.namespace.label.domain: finance
</pre>
|}

Следующие атрибуты обогатят данные:
* <code>dt.security_context: sre</code>
* <code>dt.cost.costcenter: it_services</code>
* <code>dt.cost.product: fin_app</code>
* <code>k8s.namespace.label.domain: finance</code>

== Настройка OpenTelemetry ==
Для '''OTLP'''-систем без ЕдиногоАгента требуются дополнительные шаги для обогащения сигнала. Этого можно добиться либо путем изменения кода для анализа файлов метаданных, предоставляемых оператором, либо с помощью переменных среды.

=== Включите автоматическую настройку экспортера OpenTelemetry OTLP (рекомендуется) ===
Автоматическая настройка экспортера '''OpenTelemetry OTLP''' — рекомендуемый вариант для конфигураций '''OTLP''' без внедрения ЕдиногоАгента, поскольку она обеспечивает обогащение данных, сопоставимое с вариантом с ЕдиногоАгентом. Включите её в '''DynaKube''', чтобы автоматически обогащать телеметрию метаданными Ключ-АСТРОМ. Эта функция доступна для всех языков, поддерживаемых '''OpenTelemetry'''.

=== Обогащение за счет изменений кода ===
Этот вариант подходит для автономных установок '''OTLP''' без внедрения ЕдиногоАгента. Для достижения оптимальных результатов обогатите телеметрию '''OTLP''', проанализировав файлы метаданных Ключ-АСТРОМ и добавив метаданные непосредственно в свой код, как описано в разделе «Обогащение поступающих данных полями, специфичными для Ключ-АСТРОМ». Примеры кода можно найти в нашем разделе '''OpenTelemetry''', например, для '''Java'''. Такой подход обеспечивает обогащение данных, сопоставимое с вариантом с ЕдиногоАгентом.

=== Обогащение с помощью переменной среды ===
Если внесение изменений в код невозможно, вы можете использовать переменную окружения <code>OTEL_RESOURCE_ATTRIBUTES</code> для обогащения. Однако этот метод имеет ограничения: конфигурация может быть сложной, а некоторые свойства, такие как <code>k8s.container.name</code> и теги, должны быть заданы как статические строки.

==== 1. Создайте карту конфигурации для атрибутов уровня кластера ====
* Сохраните имя '''DynaKube''': <code>DYNAKUBE="dynakube" # установите это значение на имя вашего DynaKube / kubectl get dynakube -n astromkey</code>
* Получить <code>k8s.cluster.uid</code>: <code>K8S_CLUSTER_UID="$(kubectl get dynakube -o jsonpath='{.status.kubeSystemUUID}' -n astromkey $DYNAKUBE)"</code>
* Получить <code>k8s.cluster.name</code>: <code>K8S_CLUSTER_NAME="$(kubectl get dynakube -o jsonpath='{.status.kubernetesClusterName}' -n astromkey $DYNAKUBE)"</code>
* Получить сущность '''Kubernetes''' <code>dt.entity.kubernetes_cluster</code>: <code>DT_ENTITY_KUBERNETES_CLUSTER="$(kubectl get dynakube -o jsonpath='{.status.kubernetesClusterMEID}' -n astromkey $DYNAKUBE)"</code>
* Создайте карту конфигурации в целевом пространстве имен:

{| class="wikitable"
|<pre>
kubectl create configmap astromkey-metadata \
  --from-literal K8S_CLUSTER_UID=$K8S_CLUSTER_UID \
  --from-literal K8S_CLUSTER_NAME=$K8S_CLUSTER_NAME \
  --from-literal DT_ENTITY_KUBERNETES_CLUSTER=$DT_ENTITY_KUBERNETES_CLUSTER \
  --namespace <ВАШЕ_ПРОСТРАНСТВО_ИМЕН>
</pre>
|}

==== 2. Установка атрибутов Kubernetes через API-интерфейс в Pod'е ====
Адаптируйте спецификацию вашего пода '''Kubernetes''', добавив следующие переменные среды. Вы можете включить их в манифест развертывания '''Kubernetes''' или манифест пода. Теги <code>k8s.container.name</code> нельзя задать через '''API'''-интерфейс. Их необходимо предоставлять в виде статической строки.

{| class="wikitable"
|<pre>
envFrom:
- configMapRef:
    name: astromkey-metadata
    optional: false
env:
- name: K8S_CONTAINER_NAME
  value: "" # заменить на фактическое имя контейнера
- name: K8S_POD_NAME
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: metadata.name
- name: K8S_POD_UID
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: metadata.uid
- name: K8S_POD_NAMESPACE
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: metadata.namespace
- name: K8S_WORKLOAD_KIND
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: metadata.annotations['metadata.astromkey.com/k8s.workload.kind'] # работает только при включенном обогащении метаданных
- name: K8S_WORKLOAD_NAME
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: metadata.annotations['metadata.astromkey.com/k8s.workload.name'] # работает только при включенном обогащении метаданных
- name: K8S_NODE_NAME
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: spec.nodeName
- name: DT_SECURITY_CONTEXT # работает только при настройке автоматического обогащения контекста безопасности
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: metadata.annotations['metadata.astromkey.com/dt.security_context']
- name: DT_COST_PRODUCT # работает только при настройке автоматического обогащения данных о себестоимости продукции
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: metadata.annotations['metadata.astromkey.com/dt.cost.product']
- name: DT_COST_COSTCENTER # работает только при настройке автоматического обогащения центров затрат
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: metadata.annotations['metadata.astromkey.com/dt.cost.costcenter']
</pre>
|}

==== 3. Добавить атрибуты к <code>OTEL_RESOURCE_ATTRIBUTES</code> ====
В этом примере показаны все рекомендуемые атрибуты. Удалите неиспользуемые атрибуты.

{| class="wikitable"
|<pre>
- name: OTEL_RESOURCE_ATTRIBUTES
  value: k8s.cluster.name=$(K8S_CLUSTER_NAME), k8s.cluster.uid=$(K8S_CLUSTER_UID), k8s.node.name=$(K8S_NODE_NAME), k8s.workload.name=$(K8S_WORKLOAD_NAME), k8s.workload.kind=$(K8S_WORKLOAD_KIND), k8s.pod.name=$(K8S_POD_NAME), k8s.pod.uid=$(K8S_POD_UID), k8s.namespace.name=$(K8S_POD_NAMESPACE), k8s.container.name=$(K8S_CONTAINER_NAME), dt.entity.kubernetes_cluster=$(DT_ENTITY_KUBERNETES_CLUSTER), dt.security_context=$(DT_SECURITY_CONTEXT), dt.cost.costcenter=$(DT_COST_COSTCENTER), dt.cost.product=$(DT_COST_PRODUCT)
</pre>
|}

Чтобы узнать, как обогащать сигналы метаданными о релизах с помощью переменной среды <code>OTEL_RESOURCE_ATTRIBUTES</code>, обратитесь к подробным инструкциям по стратегиям определения версий.

== Ограничения ==
* Ограничение: 20 правил на область конфигурации.
* После создания или изменения правил подождите до 45 минут, пока изменения вступят в силу. По истечении этого времени перезапустите свои поды.
* Аннотации пода, заданные вручную, <code>metadata.astromkey.com</code> имеют приоритет.
* Добавленные вручную атрибуты (любые, кроме <code>dt.security_context</code>, <code>dt.cost.costcenter</code>, или <code>dt.cost.product</code>) не обогащают метрики '''Kubernetes''' или события '''Kubernetes'''.
* Подход, основанный на настройках, не работает в сочетании с вручную применяемыми специальными аннотациями для модулей. Одновременное использование обоих подходов может вызвать конфликты и привести к непредсказуемому поведению.

== Поиск неисправностей ==
=== Проверьте определение правила ===
* Убедитесь, что каждое правило указывает на правильный тип метаданных (<code>label</code> в отличие от <code>annotation</code>).
* Убедитесь, что исходный ключ в правиле точно совпадает с ключом, существующим в пространстве имен.

=== Убедитесь, что исходные метаданные действительно существуют ===
Откройте пространство имен в приложении '''Kubernetes''' Ключ-АСТРОМ и найдите ожидаемые метки/аннотации. В качестве альтернативы выполните:

<code>kubectl get namespace <name> -o yaml</code>

и осмотрите разделы <code>metadata.labels</code> и <code>metadata.annotations</code>.

=== Убедитесь, что функция обогащения метаданных включена ===
* Убедитесь, что опция <code>metadataEnrichment.enabled: true</code> включена в конфигурации '''DynaKube'''.
* Если вы указываете <code>namespaceSelector</code> в '''DynaKube''', убедитесь, что оно соответствует тестируемому пространству имен.

=== Убедитесь, что обогащение достигло капсул ===
Проверьте любой под в этом пространстве имен:

<code>kubectl get pod <pod-name> -o yaml</code>

Ищите аннотации, начинающиеся с <code>metadata.astromkey.com/…</code>. Их наличие означает, что метаданные обогащены.

== Примеры ==
=== Правила ===
Правила в <code>builtin:kubernetes.generic.metadata.enrichment</code>

{| class="wikitable"
|<pre>
"rules":
  [
    {
      # правило #1
      "type": "Annotation",
      "source": "metadata.example.com/team",
      "target": "dt.security_context"
    },
    {
      # правило #2
      "type": "Label",
      "source": "department",
      "target": "dt.cost.costcenter"
    },
    {
      # правило #3
      "type": "Label",
      "source": "app/name",
      "target": "dt.cost.product"
    },
    {
      # правило #4
      "type": "Label",
      "source": "domain",
      "primaryGrailTag": "true"
    }
  ]
</pre>
|}

=== Пространство имен ===
Ваши существующие метки и аннотации пространства имен:

{| class="wikitable"
|<pre>
metadata:
  annotations:
    metadata.example.com/team: sre
  labels:
    metadata.astromkey.com/department: it_services
    metadata.astromkey.com/app/name: fin_app
    metadata.astromkey.com/domain: finance
</pre>
|}

=== Под ===
Оператор создаст аннотации для подов:

{| class="wikitable"
|<pre>
metadata:
  annotations:
    metadata.astromkey.com: |
      {
        "dt.security_context": "sre",
        "dt.cost.costcenter": "it_services",
        "dt.cost.product": "fin_app",
        "k8s.namespace.label.domain": "finance"
      }
</pre>
|}

=== Телеметрия ===
В данные будут добавлены следующие атрибуты:
* <code>dt.security_context: sre</code>
* <code>dt.cost.costcenter: it_services</code>
* <code>dt.cost.product: fin_app</code>
* <code>k8s.namespace.label.domain: finance</code>