Создайте пользовательскую задачу сбора метрик Prometheus в вашем кластере Kubernetes с помощью CRD.

Настройка коллекции метрик Prometheus из кластера Kubernetes описывает, как использовать ConfigMap для настройки срезов метрик Prometheus из целевых объектов по умолчанию в кластере Kubernetes. В этой статье описывается, как использовать пользовательские определения ресурсов (CRD), чтобы создавать задания по сбору данных для дальнейшей настройки и добавления новых целевых объектов.

Пользовательские определения ресурсов (CRD)

Включение управляемой службы Azure Monitor для Prometheus автоматически развертывает пользовательские определения ресурсов (CRD) для мониторов pod и мониторов служб. Эти CRD совпадают с мониторами Pod OSS и мониторами служб OSS для Prometheus, за исключением того, что изменено имя группы. Если в вашем кластере уже существуют CRD Prometheus и пользовательские ресурсы, эти CRD не будут конфликтовать с CRD, созданными дополнением. В то же время управляемая надстройка Prometheus не распознаёт CRD, созданные для OSS Prometheus. Это разделение намеренно выполнено для изоляции заданий парсинга.

Создать Pod или монитор службы

Используйте шаблоны Pod и Service Monitor и следуйте спецификации API для создания пользовательских ресурсов (PodMonitor и Service Monitor). Единственное изменение, необходимое для существующих CR OSS (настраиваемых ресурсов) для интеграции с управляемым Prometheus — изменение группы API на azmonitoring.coreos.com/v1.

Мониторы pod и сервиса должны выглядеть следующим образом:

Пример монитора pod

# Note the API version is azmonitoring.coreos.com/v1 instead of monitoring.coreos.com/v1
apiVersion: azmonitoring.coreos.com/v1
kind: PodMonitor

# Can be deployed in any namespace
metadata:
  name: reference-app
  namespace: app-namespace
spec:
  labelLimit: 63
  labelNameLengthLimit: 511
  labelValueLengthLimit: 1023

  # The selector specifies which pods to filter for
  selector:

    # Filter by pod labels
    matchLabels:
      environment: test
    matchExpressions:
      - key: app
        operator: In
        values: [app-frontend, app-backend]

    # [Optional] Filter by pod namespace. Required if service is in another namespace.
    namespaceSelector:
      matchNames: [app-frontend, app-backend]

  # [Optional] Labels on the pod with these keys will be added as labels to each metric scraped
  podTargetLabels: [app, region, environment]

  # Multiple pod endpoints can be specified. Port requires a named port.
  podMetricsEndpoints:
    - port: metricscs from the exa

Пример монитора служб

# Note the API version is azmonitoring.coreos.com/v1 instead of monitoring.coreos.com/v1
apiVersion: azmonitoring.coreos.com/v1
kind: ServiceMonitor

# Can be deployed in any namespace
metadata:
  name: reference-app
  namespace: app-namespace
spec:
  labelLimit: 63
  labelNameLengthLimit: 511
  labelValueLengthLimit: 1023

  # The selector filters endpoints by service labels.
  selector:
    matchLabels:
      app: reference-app

  # Multiple endpoints can be specified. Port requires a named port.
  endpoints:
  - port: metrics

Разверните Pod или мониторинг службы

Разверните pod или монитор службы, как показано в следующих примерах, используя kubectl apply.

Создание примера приложения

Разверните пример приложения, предоставляющего метрики Prometheus для настройки с использованием мониторинга Pod/Service.

kubectl apply -f https://raw.githubusercontent.com/Azure/prometheus-collector/refs/heads/main/internal/referenceapp/prometheus-reference-app.yaml

Создайте монитор pod и/или монитор службы для сбора метрик

Разверните монитор pod, настроенный для очистки приложения на предыдущем шаге.

Pod монитор

kubectl apply -f https://raw.githubusercontent.com/Azure/prometheus-collector/refs/heads/main/otelcollector/deploy/example-custom-resources/pod-monitor/pod-monitor-reference-app.yaml

Монитор сервисов

kubectl apply -f https://raw.githubusercontent.com/Azure/prometheus-collector/refs/heads/main/otelcollector/deploy/example-custom-resources/service-monitor/service-monitor-reference-app.yaml

Устранение неполадок

При успешном применении мониторов pod или сервисов надстройка должна автоматически начать сбор метрик с целевых объектов. Ознакомьтесь с коллекцией метрик Prometheus в Azure Monitor для общего устранения неполадок с пользовательскими ресурсами, а также для обеспечения отображения целевых объектов в 127.0.0.1/targets.

Очистка параметров конфигурации

В следующих разделах описаны параметры, поддерживаемые в файле конфигурации Prometheus, используемом в CRD. Дополнительные сведения об этих параметрах см. в справочнике по конфигурации Prometheus .

Глобальные параметры

Формат конфигурации для глобальных параметров совпадает с конфигурацией OSS prometheus.

global:
  scrape_interval: <duration>
  scrape_timeout: <duration>
  external_labels:
    <labelname1>: <labelvalue>
    <labelname2>: <labelvalue>
scrape_configs:
  - <job-x>
  - <job-y>

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

Очистка конфигураций

Поддерживаемые методы обнаружения целевых объектов для пользовательских ресурсов в настоящее время являются pod и монитором служб.

Мониторы подов и служб

Целевые объекты, обнаруженные с помощью мониторов pod и служб, имеют разные __meta_* метки в зависимости от используемого монитора. Метки в relabelings разделе можно использовать для фильтрации целевых объектов или замены меток для целевых объектов. Ознакомьтесь с примерами мониторов pod и служб.

Переименования

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

Добавление метки Добавьте новую метку, названную example_label, со значением example_value, для каждой метрики задания. Используйте __address__ в качестве исходной метки только потому, что эта метка всегда существует и добавляет метку для каждого целевого объекта задания.

relabelings:
- sourceLabels: [__address__]
  targetLabel: example_label
  replacement: 'example_value'

Используйте метки Pod или ServiceMonitor

Целевые объекты, обнаруженные с помощью мониторов pod и служб, имеют разные __meta_* метки в зависимости от используемого монитора. Метки __* удаляются после обнаружения целевых объектов. Чтобы использовать их для фильтрации на уровне метрик, сначала присвойте им имя метки с помощью relabelings. Затем используется metricRelabelings для фильтрации.

# Use the kubernetes namespace as a label called 'kubernetes_namespace'
relabelings:
- sourceLabels: [__meta_kubernetes_namespace]
  action: replace
  targetLabel: kubernetes_namespace

# Keep only metrics with the kubernetes namespace 'default'
metricRelabelings:
- sourceLabels: [kubernetes_namespace]
  action: keep
  regex: 'default'

Перемаркировка заданий и экземпляров

Вы можете изменить значения меток job и instance на основе исходной метки, как и значения любой другой метки.

# Replace the job name with the pod label 'k8s app'
relabelings:
- sourceLabels: [__meta_kubernetes_pod_label_k8s_app]
  targetLabel: job

# Replace the instance name with the node name. This is helpful to replace a node IP
# and port with a value that is more readable
relabelings:
- sourceLabels: [__meta_kubernetes_node_name]
  targetLabel: instance

Переназначения метрик

Изменения метрик применяются после слома и перед приемом. Используйте раздел metricRelabelings для фильтрации метрик после сбора. См. следующие примеры.

Удаление метрик по имени

# Drop the metric named 'example_metric_name'
metricRelabelings:
- sourceLabels: [__name__]
  action: drop
  regex: 'example_metric_name'

Сохранение только определенных метрик по имени

# Keep only the metric named 'example_metric_name'
metricRelabelings:
- sourceLabels: [__name__]
  action: keep
  regex: 'example_metric_name'

# Keep only metrics that start with 'example_'
metricRelabelings:
- sourceLabels: [__name__]
  action: keep
  regex: '(example_.*)'

Фильтрация метрик по меткам

# Keep metrics only where example_label = 'example'
metricRelabelings:
- sourceLabels: [example_label]
  action: keep
  regex: 'example'

# Keep metrics only if `example_label` equals `value_1` or `value_2`
metricRelabelings:
- sourceLabels: [example_label]
  action: keep
  regex: '(value_1|value_2)'

# Keep metrics only if `example_label_1 = value_1` and `example_label_2 = value_2`
metricRelabelings:
- sourceLabels: [example_label_1, example_label_2]
  separator: ';'
  action: keep
  regex: 'value_1;value_2'

# Keep metrics only if `example_label` exists as a label
metricRelabelings:
- sourceLabels: [example_label_1]
  action: keep
  regex: '.+'

Переименование метрик Переименование метрик не поддерживается.

Базовая аутентификация и токены Bearer

Ограниченный доступ к секретам для Pod/ServiceMonitors

Начиная с Kubernetes 1.37, Azure Managed Prometheus (или ama-metrics) будет использовать доступ к секретам Kubernetes в пределах пространства имен в конфигурациях PodMonitor и ServiceMonitor. Ранее компонент ama-metrics имел разрешения на уровне всего кластера для чтения секретов во всех пространствах имен. Это обновление повышает безопасность, требуя явного доступа на уровне пространства имен к секретам, используемым для базовой проверки подлинности

При этом изменении:

• Доступ к секретам ограничен только пространствами имен, которые вы явно настраиваете
• Необходимо предоставить разрешения на управление доступом на основе ролей (RBAC) в каждом пространстве имен, где используются секреты.

Поведение по умолчанию по версии Kubernetes

Версии Kubernetes до версии 1.37

• Доступ к секретам на уровне кластера по-прежнему включен для обратной совместимости
• Выполните действия, описанные здесь , чтобы настроить базовую проверку подлинности для ServiceMonitor и PodMonitor

Kubernetes версии 1.37 и более поздних версий

• Доступ к секретам на уровне кластера удаляется
• По умолчанию ни одно пространство имен не отслеживается на предмет секретов
• Вы должны:
  1. Настройте разрешенные пространства имен
  2. Добавьте права RBAC в каждом пространстве имён

Когда необходимо настроить эту настройку

Необходимо настроить доступ к секретам в пределах пространства имён, если вы используете Kubernetes версии 1.37 или более поздней и ваш ServiceMonitor или PodMonitor использует basicAuth и любую конфигурацию, которая ссылается на секреты Kubernetes.

Настроить доступ к секретам для PodMonitor и ServiceMonitor для базовой аутентификации

Выполните следующие действия, чтобы разрешить Azure Managed Prometheus безопасно читать секреты.

Шаг 1. Создание базового секрета проверки подлинности

Создайте секрет в пространстве имен, где выполняется приложение:

apiVersion: v1
kind: Secret
metadata:
  name: my-basic-auth
  namespace: my-app          # <-- your application namespace
type: Opaque
data:
  username: <base64-encoded-username>
  password: <base64-encoded-password>

Шаг 2. Ссылка на секрет в ServiceMonitor/PodMonitor

Пример ServiceMonitor:

apiVersion: azmonitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-service-monitor
  namespace: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  endpoints:
    - port: metrics
      basicAuth:
        username:
          name: my-basic-auth    # Secret name from Step 1
          key: username
        password:
          name: my-basic-auth
          key: password

Пример PodMonitor:

apiVersion: azmonitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: my-pod-monitor
  namespace: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  podMetricsEndpoints:
    - port: metrics
      basicAuth:
        username:
          name: my-basic-auth
          key: username
        password:
          name: my-basic-auth
          key: password

Шаг 3. Настройка secrets_access_namespaces

Измените ama-metrics-settings-configmap.yaml, чтобы указать пространства имён, в которых хранятся ваши секреты:

kind: ConfigMap
apiVersion: v1
metadata:
  name: ama-metrics-settings-configmap
  namespace: kube-system
data:
  prometheus-collector-settings: |-
    cluster_alias = ""
    secrets_access_namespaces = "kube-system,my-app"

Шаг 4: Создайте RBAC в каждом пространстве имен (Kubernetes >= 1.37)

В Kubernetes >= 1.37 ClusterRole больше не предоставляет доступ ко всем секретам кластера. Необходимо создать Role и RoleBinding в каждом пространстве имен, указанном в secrets_access_namespaces (включая kube-system при необходимости). Примените следующее в каждом пространстве имен. Замените my-app целевое пространство имен:

Создайте роль:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: ama-metrics-secrets-reader
  namespace: my-app              # <-- repeat for each namespace
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "list", "watch"]

Создайте RoleBinding:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: ama-metrics-secrets-rolebinding
  namespace: my-app              # <-- repeat for each namespace
subjects:
  - kind: ServiceAccount
    name: ama-metrics-serviceaccount
    namespace: kube-system       # <-- SA lives in kube-system
roleRef:
  kind: Role
  name: ama-metrics-secrets-reader
  apiGroup: rbac.authorization.k8s.io

Шаг 5: Проверьте

После перезапуска ama-metrics pod:

1. Проверьте журналы целевого распределителя:

   SecretsAccessNamespaces from configmap: [kube-system my-app]
   

2. Убедитесь, что цели ServiceMonitor/PodMonitor отображаются в списке обнаруженных целей распределителя целей.
3. Убедитесь, что результаты сбора метрик включают метрики из эндпоинтов, защищённых базовой аутентификацией.

Пример: несколько пространств имен

Если у вас есть секреты в my-app, backendи monitoring:

1. Параметр ConfigMap:

   secrets_access_namespaces = "kube-system,my-app,backend,monitoring"
   

2. RBAC (>только для 1.37): Создайте Role + RoleBinding (из шага 4) в каждом из my-app, backend и monitoring.

Устранение неполадок

Настройка базовой проверки подлинности для Kubernetes 1.36 и более ранних версий

Целевые объекты очистки с помощью базовых маркеров проверки подлинности или носителя поддерживаются с помощью PodMonitors и ServiceMonitors. Убедитесь, что секрет, содержащий имя пользователя, пароль или токен, находится в том же пространстве имен, что и монитор pod/service. Это поведение аналогично поведению OSS prometheus-operator.

Очистка на основе TLS

Если вы хотите собирать метрики Prometheus с конечной точки HTTPS, в конфигурации Prometheus, PodMonitor или ServiceMonitor для scheme должно быть задано значение https, а также должны быть указаны дополнительные настройки TLS.

1. Создайте секрет с именем ama-metrics-mtls-secret в пространстве имён kube-system. Каждая пара "ключ-значение", указанная в разделе данных секретного объекта, будет подключена в качестве отдельного файла в этом расположении /etc/prometheus/certs с именами файлов, которые совпадают с ключами, указанными в разделе данных. Значения секретов должны быть закодированы в кодировке Base64.

   Ниже приведен пример YAML секрета:

   apiVersion: v1
   kind: Secret
   metadata:
     name: ama-metrics-mtls-secret
     namespace: kube-system
   type: Opaque
   data:
     <certfile>: base64_cert_content    
     <keyfile>: base64_key_content 
   

   Секрет ama-metrics-mtls-secret смонтирован в поды ama-metrics по пути /etc/prometheus/certs/ и доступен для средства сбора метрик Prometheus. Ключ будет именем файла. Это значение декодируется из Base64 и добавляется как содержимое файла в контейнере.

2. Укажите файловый путь в конфигурации Prometheus, PodMonitor или ServiceMonitor:

   • Используйте следующий пример, чтобы указать параметр конфигурации TLS для PodMonitor или ServiceMonitor:

    tlsConfig:
      ca:
        secret:
          key: "<certfile>"
          name: "ama-metrics-mtls-secret"
      cert:
        secret:
          key: "<certfile>"
          name: "ama-metrics-mtls-secret"
      keySecret:
          key: "<keyfile>"
          name: "ama-metrics-mtls-secret"
      insecureSkipVerify: false
   

Базовая проверка подлинности и TLS

Если вы хотите использовать базовый маркер проверки подлинности или маркер носителя (учетные данные на основе файлов) и параметры проверки подлинности TLS в CRD, убедитесь, что секрет ama-metrics-mtls-secret включает все ключи в разделе данных с соответствующими значениями в кодировке Base64, как показано ниже:

apiVersion: v1
kind: Secret
metadata:
  name: ama-metrics-mtls-secret
  namespace: kube-system
type: Opaque
data:
  certfile: base64_cert_content    # used for TLS
  keyfile: base64_key_content      # used for TLS
  password1: base64-encoded-string # used for basic auth
  password2: base64-encoded-string # used for basic auth

Следующие шаги

• Дополнительные сведения о сборе метрик Prometheus.